RRatesSpot
← Docs

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 id you'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.