← Bookings API

Booking webhooks

Receive a full booking when it changes. Connect Make, Airtable or your own receiver without fetching the same bookings on every run.

Register your receiver

  1. A full company owner opens Settings → API → Booking webhooks.
  2. Add a public HTTPS URL on port 443, select events, and accept the booking-data disclosure.
  3. Save the signing secret immediately. It is shown once; TourDash stores it encrypted in Vault.
  4. Configure signature verification, send a synthetic test event, then refresh the delivery log.

Each company can register ten endpoints. Guides and city-scoped managers cannot manage them. Endpoints must have a valid TLS certificate. Private, loopback, link-local, multicast, reserved and mapped/tunnel addresses are rejected. All DNS answers are checked again for every attempt; the connection uses a checked IP while retaining hostname certificate verification. Redirects are treated as failures.

Events and payloads

The data object has the same shape as one booking from GET /api/v1/bookings. It includes contact details, counts, attendance, notes and tour details, so receivers do not need another fetch. Test events have is_test: true, booking ID 0 and synthetic guest details. Deleting a booking is not a cancellation event.

{
  "id": "bce83d69-81cf-4b8d-8ac6-698290199540",
  "type": "booking.updated",
  "created_at": "2026-11-14T12:00:00Z",
  "updated_at": "2026-11-14T12:00:00Z",
  "is_test": false,
  "data": {
    "id": 123,
    "ext_ref": "EXAMPLE-123",
    "tour": {
      "name": "Old Town",
      "start_time": "2026-11-15T09:00:00",
      "language": "en"
    },
    "contact": {
      "name": "Example guest",
      "phone": null,
      "email": null
    },
    "platform": "tourdash",
    "booked": {
      "adults": 2,
      "children": 0,
      "infants": 0
    },
    "attended": {
      "adults": null,
      "children": null,
      "infants": null
    },
    "checked_in_by": null,
    "notes": null,
    "status": "new",
    "received_at": "2026-11-01T10:00:00Z",
    "updated_at": "2026-11-14T12:00:00Z"
  }
}

Delivery and ordering

Capture never performs HTTP inside a booking save. Repeated changes for the same booking and event type within a 45-second window are combined into the latest full snapshot. Creation and cancellation remain distinct from updates. A worker runs every minute; canonical tour changes are expanded in bounded batches, so large renames may take several runs.

Delivery is at least once and unordered. Durably deduplicate by the envelope id. Keep the newest data.updated_at for each booking so an older event cannot overwrite a newer snapshot. Return a 2xx response within ten seconds; response bodies are ignored. A timeout after your receiver commits can produce a duplicate.

There are six attempts: the initial request, then retries after approximately 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. Scheduling and downtime can delay attempts. Ten consecutive failed attempts across an endpoint pause it and enqueue an email to its full company owners. Review the log, fix the receiver, and enable it again. A successful attempt resets the consecutive-failure count.

Verify signatures and reject replays

Every POST has X-TourDash-Event-Id and X-TourDash-Signature: t=UNIX_SECONDS,v1=HEX_DIGEST. The digest is HMAC-SHA256 of timestamp + "." + rawRequestBody, using the full signing secret. Check signatures with a timing-safe comparison and reject timestamps more than five minutes from your server clock. A fresh timestamp/signature is generated for every attempt.

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

function verify(rawBody, header, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
  if (!match || Math.abs(Date.now()/1000 - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.' + rawBody).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(match[2]));
}
// Verify BEFORE JSON.parse. Use the complete whsec_... secret as the HMAC key.
// Durably deduplicate event.id, queue work, then return 204 promptly.

Rotating a secret changes future attempts immediately. An already claimed request may still use the previous key for up to two minutes; keep the previous key briefly during rotation. Neither logs nor moderator views reveal secrets. Removing an endpoint deletes its secret and stops future claims; a request already in flight may finish.

Logs, redelivery and polling recovery

Owners can inspect HTTP status, elapsed time and safe error categories for each attempt. No receiver response body is retained. Use Redeliver for a delivered or failed event from the last seven days after enabling its endpoint. Redelivery keeps the original event ID and payload, so a receiver that already processed it should acknowledge it without repeating work.

Keep polling as a backstop for capture failures or interruptions. Use ?updated_since=..., finish all pages, upsert by booking ID and persist sync.next_updated_since. The watermark includes a two-minute overlap. The incremental lookback is 31 days; use a date-range sync for older recovery. No historical webhook backlog is created when an endpoint is registered.

Booking data disclosure and retention

Webhooks transmit guest names, email addresses, phone numbers, booking/attendance details and booking notes to destinations selected by the company owner. Register a receiver only if you are authorized to share that data and have arranged appropriate access, security and retention with its operator. The owner must accept this disclosure when registering each endpoint.

TourDash webhook payload copies expire after seven days; delivery and attempt metadata expire after 30 days, through bounded maintenance runs every minute. Expired payloads cannot be redelivered. These limits apply to TourDash's webhook copies, not to the original booking record or copies held by your receiver. Keep guest data and account credentials out of URL query parameters, and treat provider-generated webhook URLs as secrets.

See the webhook terms and privacy disclosure.