Webhooks
Webhooks notify your integration when data changes, so you can keep a local copy fresh without polling. Register an HTTPS endpoint with POST /webhooks, choosing which of the event types listed by GET /webhook_events it should receive.
Events describe what changed, not the new values. A delivery names the listings affected and expects you to re-read the detail through the relevant endpoint — price recommendations, reservations or flags. This keeps payloads small and stable, and means you never have to reconcile a webhook body against an API response.
Deliveries are batched. Events occurring within a five-minute window collapse into a single request whose data.listing_ids names every listing involved, so a nightly repricing run across a large portfolio arrives as a handful of requests rather than thousands. Each delivery only ever names listings you have access to.
Verify every delivery. Requests carry a Wh-Signature header of the form t=<unix timestamp>,v1=<hex>, where the hex is HMAC-SHA256(secret, "<t>.<raw request body>"). Recompute it with the subscription's secret and compare; reject the request if it does not match, or if t is older than your tolerance (five minutes is a reasonable choice) to prevent replay. The secret is returned only when the subscription is created and by POST /webhooks/\{id\}/rotate_secret — it cannot be read back afterwards.
Delivery is at-least-once, so de-duplicate. Retries reuse the same Wh-Event-Id header (also data-adjacent as the envelope id); treat a repeated id as already handled. Respond with any 2xx status as soon as you have durably accepted the request — do not do your processing before responding, since we time out after 15 seconds. Failed attempts are retried with backoff over roughly 20 minutes, and a subscription that keeps failing is disabled automatically; re-enable it with PUT /webhooks/{id} once your endpoint is healthy. Use GET /webhooks/{id}/deliveries to see what we actually sent and what your endpoint returned.
List subscribable event types.
Returns every event type a webhook subscription can ask for, with the object its ids refer to and how long events of that type are batched before being sent. Use the `event_type` values in `event_types` when creating or updating a subscription.
List webhook subscriptions.
Returns the webhook subscriptions belonging to the authenticated user, most recently created first. Signing secrets are **not** included — they are only available when a subscription is created or its secret is rotated.
Create a webhook subscription.
Registers an HTTPS endpoint to receive the given event types. The subscription covers the authenticated user's entire portfolio — owned listings plus listings shared with them to manage — and each delivery names only listings they can access.
Get a webhook subscription.
Returns one of the authenticated user's webhook subscriptions, without its signing secret. Responds `404` for a subscription belonging to another account.
Update a webhook subscription.
Updates the fields provided and leaves the rest unchanged. Passing `event_types` **replaces** the subscribed set rather than adding to it; omitting it leaves the current set alone.
Delete a webhook subscription.
Removes the subscription and stops all delivery to it. Its delivery history is removed with it.
Rotate a webhook signing secret.
Issues a new signing secret and returns it. Use this if the current secret has leaked or been lost.
List recent delivery attempts.
Returns recent deliveries for the subscription, most recent first, with the HTTP status the endpoint returned and the reason for any failure. Use it to confirm what was sent and to diagnose an endpoint that is failing verification or timing out.