Webhooks and events
RatesSpot tells your app when something happens: a booking is confirmed, paid, cancelled, checked in; a price or listing changes. Owners add endpoints in the dashboard (or POST /v1/webhook-endpoints); the response includes the signing secret (whsec_…) once.
What you receive
{
"id": "evt_…",
"type": "booking.confirmed",
"createdAt": "2026-12-08T10:00:00.000Z",
"merchantId": "…",
"livemode": true,
"data": { "bookingId": "…", "booking": { "…the booking as it was at that moment…" } }
}
Types: hold.created, hold.expired, booking.confirmed, booking.changed, booking.cancelled, booking.checked_in, booking.completed, booking.no_show, payment.succeeded (with method), payment.failed, refund.created, refund.sent, instalment.overdue, contract.terminated, availability.changed, catalog.changed.
Check it's from RatesSpot
Every request has RatesSpot-Signature: t=<unix>,v1=<hex>: HMAC-SHA256 of t.body with your secret. Use the raw body.
import { verifyWebhook } from "@ratesspot/sdk";
const raw = await request.text();
if (!(await verifyWebhook(raw, request.headers.get("ratesspot-signature"), process.env.RATESSPOT_WEBHOOK_SECRET!))) {
return new Response("bad signature", { status: 400 });
}
const event = JSON.parse(raw);
Rules of delivery
- At least once. You may get an event twice: skip an
idyou've handled. - Not in order. Compare
createdAt, or fetch the latest state. - Answer 2xx quickly, then do the work. Anything else is retried for about 3 days; after that the endpoint is switched off and the owner sees why in the dashboard.
- Catch up after downtime with
GET /v1/events(last 30 days, same envelopes).
Your own data on RatesSpot objects
Store ids from your system in metadata on bookings, listings, rates, courses and the business (PATCH /v1/bookings/{id} with { "metadata": { "invoice": "INV-204" } }), then find bookings with GET /v1/bookings?metadata=invoice:INV-204. Up to 50 string keys; an empty string removes one. Public (publishable) keys can't set it.