Webhooks

Add an HTTPS endpoint under Webhooks in the portal and pick the events it should receive. Each endpoint gets its own signing secret, shown once.

The same thing works over the API: POST /v1/webhooks/endpoints, GET /v1/webhooks/endpoints, PATCH and DELETE on one endpoint, POST /{id}/rotate-secret and POST /{id}/test — the same store behind both doors, so the portal and your code never disagree about where your events go.

Send a test delivery before anything real depends on it. Today that is an API call, POST /v1/webhooks/endpoints/{id}/test; there is no button for it in the portal yet. It goes out over the same path as a live event — same TLS, same signature, same delivery log — so it proves your endpoint is reachable and your signature check is right.

These four are produced by real code paths and will arrive at a subscribed endpoint. Every payload carries the event id, type, createdAt and a data object.

The event catalog — in the portal form, in GET /v1/account's neighbours and in the OpenAPI enum — also contains the following, and nothing in the platform publishes them today. Subscribing to one is not coverage; it is silence that looks like coverage. Build against a poll or a reconciliation job instead, and ask your Vacabee contact before you design around any of them.

Every delivery carries an X-Vacabee-Signature header with a timestamp and an HMAC-SHA256 signature:

X-Vacabee-Signature: t=1756483200,v1=5f2b8c1d…

To verify, in this order:

• Take the raw request body — the bytes as received. Parsing and re-serialising the JSON changes them and the signature will not match.
• Build the signed payload as `${t}.${rawBody}`.
• Compute HMAC-SHA256 over it with the endpoint's signing secret and compare with v1 using a constant-time comparison.
• Reject the delivery if t is more than five minutes away from your clock. Without that check a captured delivery can be replayed at any time in the future.

import { webhookHandler, memoryDeduplicator } from "@vacabee/partner-api";

const hooks = webhookHandler({
  secret: process.env.VACABEE_WEBHOOK_SECRET!,
  // Delivery is at least once. Swap this for Redis or a unique column
  // on event.id in production — this one is per-process and forgets on restart.
  seen: memoryDeduplicator(),
  // Acknowledge first, then work: we wait ten seconds for your response.
  respondFirst: true,
  on: {
    "booking.confirmed": async (event) => {
      await db.bookings.upsert(event.data.bookingReference, event.data);
    },
    "payment.refunded": async (event) => {
      await ledger.credit(event.data);
    },
  },
  onError: (err, ctx) => log.warn({ err, delivery: ctx.deliveryId }),
});

// Next.js / Bun / Deno / Cloudflare Workers
export const POST = hooks.fetch;

// Express — express.raw is required, see below
app.post("/vacabee/webhooks", express.raw({ type: "application/json" }), hooks.express);

If you would rather not take the dependency, the check is: split the header into t and v1, reject if t is more than 300 seconds from your clock, compute HMAC-SHA256(secret, `${t}.${rawBody}`) as hex, and compare against every v1 in the header with a constant-time comparison.

There can be more than one v1 in the header. A normal rotation keeps the previous secret alive for 24 hours and signs every delivery in that window with both secrets, so you can deploy the new one without losing an event. Accept the delivery if any v1 matches — the SDK already does.

• Answer with any 2xx as soon as you have durably stored the event. We wait ten seconds for your response — a handler that books, emails and writes to three systems before answering will run past that and earn a retry it did not need. The SDK's respondFirst option acknowledges first and runs your handler afterwards.
• A non-2xx or a timeout is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours — seven attempts over about 32 hours, which covers an outage that starts on a Friday evening. After that the delivery is marked exhausted and stops on its own. It is not lost: it stays in the history and you can resend it by hand once your endpoint is healthy.
• 410 Gone is the one status we do not retry. It is read as “this route is deliberately gone” and the delivery is marked failed after the first attempt. If your gateway or CDN answers 410 for a removed route during a deploy, you lose those events instead of getting the 32-hour buffer — answer 503 during deploys, not 410.
• A single bad event never disables your endpoint. Ten consecutive deliveries that end in failed or exhausted do. Note that a 410 counts towards that after one attempt, so ten quick 410s can switch an endpoint off in minutes rather than over days. A disabled endpoint stops receiving until you re-enable it, and nothing notifies you — check status on the endpoint if events go quiet.
• Delivery is at least once. The same event can arrive twice — deduplicate on the event id and make your handler safe to run again.
• Ordering is not guaranteed. Two events about the same booking can arrive out of order; use the payload's state and timestamp, not arrival order.
• Every attempt is kept for 30 days. GET /v1/webhooks/deliveries lists them — status, event type, timestamps — and GET /v1/webhooks/deliveries/{id} is the one that carries the payload and the per-attempt detail: the request headers we sent, the status code and the response body you returned. Both are in the portal too.
• A retry sends the same stored payload again, serialised from the record we kept, with a signature computed fresh for the new timestamp. Byte-compare it against your own copy of an earlier attempt only if you are prepared for JSON key ordering to differ from the original producer.
• GET /v1/webhooks/deliveries?status=EXHAUSTED is the list that needs you: those are the events where the automatic attempts ran out and nothing more happens on its own. The SDK will page through them for you — for await (const d of client.deliveries.all({ status: "EXHAUSTED" })), then client.deliveries.retry(d.id).
• Webhook deliveries are never billable and never count against your search quota.