Signed webhooks

Receive bookings, payments, cancellations and settlements in your system as they happen, with HMAC signatures and automatic retries.

Available events

Among others: booking.order.*, booking.item.redeemed, payments.payment.*, payments.refund.succeeded, billing.settlement.paid and rewards.payout.paid. The full list is at GET /webhooks/events.

Subscribing

From Channel → Integrations or with POST /orgs/:org/webhooks you provide a public https URL and the events you want. The response includes the signing secret only once; you can rotate it at any time.

Delivery and signature

Each event arrives as a JSON POST with the headers roamdia-event-id, roamdia-event-type, roamdia-delivery-id and:

roamdia-signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>

Verify the signature over the body exactly as received, before parsing the JSON:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, rawBody, header, toleranceSeconds = 300) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1, 'hex');
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Retries

Respond with 2xx within 5 seconds. Otherwise it is retried after 30 s, 2 min, 10 min, 1 h, 6 h and 24 h. Use roamdia-event-id to discard duplicates. The dashboard has the delivery history, manual retry and a test event.