# 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

```json
{
  "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.

```ts
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.
