Webhooks

These are server-to-server callbacks — external services POST events to your VanityPass API instance. Unlike regular API endpoints, webhook handlers do not require an X-Api-Key or Authorization header. Instead, each request is authenticated via HMAC signature verification on the VanityPass side.

Never expose or replicate these URLs in client-facing code. They are called exclusively by trusted upstream services on VanityPass's backend.

Each webhook handler validates the X-Signature header (or the gateway's equivalent) before processing any payload. Requests with missing or invalid signatures are rejected with 401 Unauthorized.

---

Hotel Payment Webhook

POST /v1/hotel/webhook/{gateway}

Payment confirmation from the configured payment gateway for hotel bookings. VanityPass uses this event to transition a booking from pending_payment to confirmed.

Parameter	Location	Description
gateway	path	Payment gateway identifier configured for your account.
X-Signature	header	HMAC-SHA256 signature of the raw request body, using the gateway's webhook secret.

The handler verifies the signature against the configured secret for the specified gateway before updating any booking state. Replaying an already-processed event is a no-op — idempotency is enforced by event ID.

---

Travel Services Payment Webhook

POST /v1/travel/webhook/payment/{gateway}

Payment confirmation for travel service bookings, including airport lounge access, fast-track, and other travel perks processed through the payment gateway.

Parameter	Location	Description
gateway	path	Payment gateway identifier configured for your account.
X-Signature	header	HMAC-SHA256 signature of the raw request body.

Follows the same HMAC verification pattern as the hotel payment webhook. Events from different gateways carry gateway-specific payload shapes — the handler normalises these internally.

---

Stripe Payment Webhook

POST /v1/webhooks/payments/stripe

The single Stripe callback for checkout-managed and legacy hotel, lounge, experience, and ground-transport payments.

Parameter	Location	Description
Stripe-Signature	header	Stripe signature over the exact raw request body. Missing, empty, malformed, stale, or invalid signatures are rejected.

VanityPass verifies the raw body before parsing or changing booking state. Provider event IDs are deduplicated, and the payment identifier, amount, currency, environment, and current state must match before fulfilment.

---

Ground Transport Events

VanityPass receives a series of lifecycle events as a ground transport reservation progresses from creation through completion. All ground transport webhook endpoints are called by VanityPass's transport provider — no auth header is required from your side, but each payload is verified against the HMAC secret configured on the VanityPass backend.

Reservation Created

POST /v1/travel/ground-transport/webhook/reservation-created

Fired when the transport provider successfully creates a reservation. VanityPass records the reservation ID and transitions the booking to confirmed.

Reservation Cancelled

DELETE /v1/travel/ground-transport/webhook/reservation-cancelled

Fired when a reservation is cancelled — either by the traveller or by the provider (e.g. no available drivers). VanityPass marks the booking as cancelled and triggers any applicable refund logic.

Reservation Modified

PATCH /v1/travel/ground-transport/webhook/reservation-modified

Fired when booking details change (pickup time adjustment, vehicle upgrade, etc.). VanityPass updates the stored booking record and notifies the traveller if contact details are available.

Vehicle Info Assigned

POST /v1/travel/ground-transport/webhook/vehicle-info

Driver and vehicle assigned to the reservation. Payload includes driver name, vehicle make/model, licence plate, and an optional driver photo URL. VanityPass stores this for display in the traveller's itinerary.

Real-Time Tracking

POST /v1/travel/ground-transport/webhook/tracking

Real-time GPS tracking updates as the vehicle approaches the pickup point. Payload includes latitude, longitude, estimated arrival time, and booking reference. VanityPass forwards these to connected clients via its real-time layer.