Webhooks — real-time notifications

Instead of polling the API, let R2 notify your system the moment an event happens: a reservation created, modified or cancelled, a payment collected.

A webhook is a URL in your system that R2 calls with a POST whenever something you care about happens. The business owner registers the endpoint from their dashboard, picks which events to listen to, and R2 starts notifying. It is the efficient way to stay in sync: no polling, no lag.

Available events#

How to integrate, step by step#

This is the full sequence to keep your system in sync with a business’s reservations, without polling the API:

1. The owner generates the API key from their dashboard (Settings → R2 Connect API) with the read:reservations scope, and shares it with you. It is shown only once.
2. Initial backfill via the read API: walk GET /reservations, paginating until has_more is false. This runs ONCE; the webhook does not replay history from before it was registered.
3. Expose an HTTPS endpoint accepting POST with a JSON body. It must answer 2xx in under 5 seconds: acknowledge first, process in the background afterwards.
4. The owner registers the endpoint and picks the events. For lodging: reservation.created, reservation.updated and reservation.cancelled. Save the signing secret shown at registration — it appears only that once.
5. Verify the signature of every POST before acting on it (procedure below). A notification without a valid signature is discarded: it did not come from R2.
6. Deduplicate by R2-Delivery-Id, and discard events whose updated_at is older than the one you already stored for that reservation.
7. Apply the event as state, not as a diff: each notification describes how the reservation now looks. If you need the full breakdown (lines, taxes, payments), request it with GET /reservations/{order_number}.

Payload shape#

Each notification arrives as JSON. It carries the event type, when it occurred, and a data object with the key fields. For the full detail, request the resource via the API using the order_number or id.

{
  "event": "payment.succeeded",
  "occurred_at": "2026-07-16T10:20:14.907Z",
  "data": {
    "object": "payment",
    "id": "n47dk3mzq81ba5tv",
    "order_id": "p97cbaneya88az5ra",
    "order_number": "ORD-MRNCRMX2-3BAW",
    "amount": 2088,
    "currency": "MXN",
    "status": "succeeded",
    "method": "card",
    "succeeded_at": "2026-07-16T10:20:14.907Z"
  }
}

Reservation events carry the full stay. A cancellation adds cancelled_at and cancellation_reason:

{
  "event": "reservation.updated",
  "occurred_at": "2026-08-14T18:03:22.114Z",
  "data": {
    "object": "reservation",
    "id": "p97cbaneya88az5ra",
    "order_number": "ORD-MRNCRMX2-3BAW",
    "type": "booking",
    "status": "confirmed",
    "channel": "booking_com",
    "guest_name": "María Fernández",
    "check_in": "2026-09-05",
    "check_out": "2026-09-08",
    "guests": { "adults": 2, "children": 0 },
    "currency": "MXN",
    "subtotal": 8275.86,
    "tax_total": 1324.14,
    "total": 9600,
    "created_at": "2026-08-01T15:41:09.522Z",
    "updated_at": "2026-08-14T18:03:22.114Z"
  }
}

Reservation payload fields#

This is everything that travels in a reservation.created, reservation.updated or reservation.cancelled. Amounts are in the business’s currency, with decimals; stay dates use YYYY-MM-DD and timestamps use ISO 8601 (UTC).

Headers on every POST#

Verify the signature (important)#

When the webhook is registered, the owner receives a signing secret (starts with whsec_) shown only once. With it you verify that each notification comes from R2 and not from an impostor. The procedure is identical to Stripe’s:

1. Take the R2-Signature header and split t (timestamp) and v1 (signature).
2. Build the signed string: {t}.{raw_body} — the EXACT body you received, without re-serializing.
3. Compute HMAC-SHA256(secret, signed_string) in hexadecimal.
4. Compare it with v1 using constant-time comparison.
5. Reject if it does not match, or if t is older than 5 minutes (replay protection).

// Node.js / Express — webhook verification
import crypto from "node:crypto";

const SECRET = process.env.R2_WEBHOOK_SECRET; // whsec_...

// NOTE: you need the RAW body, not the parsed one.
app.post("/webhooks/r2", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("R2-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  const body = req.body.toString("utf8");

  // 1) Replay protection: reject old timestamps
  if (Math.abs(Date.now() / 1000 - t) > 300) return res.status(400).end();

  // 2) Recompute the signature
  const expected = crypto.createHmac("sha256", SECRET)
    .update(`${t}.${body}`).digest("hex");

  // 3) Constant-time comparison
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!ok) return res.status(400).end();

  // 4) Respond 2xx FAST and process afterwards
  const event = JSON.parse(body);
  enqueueForProcessing(event);       // do not block the response
  res.status(200).end();
});

# Python / Flask — webhook verification
import hmac, hashlib, time, os
from flask import request, abort

SECRET = os.environ["R2_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/r2")
def r2_webhook():
    header = dict(p.split("=") for p in request.headers.get("R2-Signature", "").split(","))
    t = int(header.get("t", "0"))
    body = request.get_data()  # raw bytes

    if abs(time.time() - t) > 300:
        abort(400)  # replay protection

    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, header.get("v1", "")):
        abort(400)

    event = request.get_json()
    enqueue_for_processing(event)
    return "", 200

Retries and reliability#

• Respond with any 2xx code to acknowledge receipt. Anything else counts as a failure.
• If your endpoint fails or does not respond, R2 retries with growing backoff: up to 6 attempts over several hours.
• An endpoint that fails many times in a row disables itself; the owner re-enables it from their dashboard once fixed.
• Respond fast (under 5 seconds): acknowledge receipt and process in the background. If you are slow, R2 treats it as a timeout and retries.
• Duplicate deliveries can happen in edge cases: use R2-Delivery-Id to deduplicate and make your processing idempotent.

Test without waiting for a real event#

From the business dashboard (Settings → R2 Connect API → Webhooks) there is a “Send test event” button that fires a signed notification with the same schema as a real one — every field in the table above, with a dummy reservation 7 days out. If the endpoint is subscribed to several events you can choose which one to fire, so you can test cancellation without actually cancelling anything. The notification carries "test": true, the order_number R2-TEST-0000 and an explanatory note, so your system can discard it without touching your data.

Delivery log#

Every delivery attempt is logged and the business owner can review it in their dashboard, in the same Webhooks section: which event it was, whether it was delivered, how many attempts it took, which HTTP code your server returned, and when. That is how a “we never got it” gets settled: you can see whether R2 tried and what your endpoint answered.

• The log keeps the last 30 days; finished deliveries are purged afterwards.
• It does not store the notification body, only the attempt outcome. If you need to audit content, log the payload on your side when you receive it.
• It lives in the business dashboard: there is no API endpoint to read the log. If you are the integrator, ask the hotel to share it when something needs diagnosing.