Webhooks

Webhooks let you receive real-time HTTP notifications when booking events occur in Proximity. Instead of polling the API for changes, your server receives a POST request whenever a booking is created, cancelled, rescheduled, or changes status.

How It Works

Configure a webhook URL in your Proximity dashboard (Settings → Webhooks)
Choose which events you want to receive
Proximity sends a POST request to your URL each time a matching event occurs
Your server responds with 200 OK to acknowledge receipt

Webhook Delivery

Webhooks are sent as HTTP POST requests with a application/json body
Each request includes signature headers for verification
Failed deliveries (non-2xx response) are retried up to 3 times with exponential backoff (30s, 2min, 10min)
Webhook payloads are delivered in near real-time (typically within a few seconds)

Request Headers

Every webhook request includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Event`	The event type (e.g., `booking.created`)
`X-Webhook-Signature`	HMAC-SHA256 signature of the request body
`X-Webhook-Delivery`	Unique delivery ID for deduplication

Envelope Format

All webhook payloads share a common envelope:


{
  "event": "booking.created",
  "createdAt": "2026-03-16T14:05:00Z",
  "payload": {
    // Event-specific data
  }
}

Field	Type	Description
`event`	`string`	Event type identifier
`createdAt`	`string`	ISO 8601 timestamp of when the event occurred
`payload`	`object`	Event-specific payload (see Events & Payloads)

Best Practices

Respond quickly — Return 200 OK as fast as possible. Process the payload asynchronously (e.g., push to a queue) rather than doing heavy work in the webhook handler.
Verify signatures — Always verify the HMAC signature to ensure requests come from Proximity.
Handle duplicates — Use the X-Webhook-Delivery header to deduplicate deliveries. The same event may be sent more than once due to retries.
Use HTTPS — Always use an HTTPS endpoint for your webhook URL.