Events and webhook delivery

Read immutable events

GET /events requires events:read and supports bounded cursor pagination with event-type, business and line filters. Persist the next cursor only after processing a page. The event feed provides a seven-day recovery window; it is not a permanent archive.

Event types are waitlist.entry.created, waitlist.entry.updated, waitlist.entry.status_changed, booking.created, booking.rescheduled, booking.cancelled. Ready and completed workflows select waitlist.entry.status_changed and inspect data.status.

Each event has an immutable id, type, schemaVersion, occurredAt, tenantId, businessId, queueId, resourceId, resourceVersion and minimal data. Event IDs are distinct from entry IDs. Supported guest-field edits emit waitlist.entry.updated with IDs and the resource version, without guest values. Use an authorized entry lookup for personal details.

Connect an available destination

Subscriptions belong to a tenant and the creating credential. Selected events and resource filters must remain within that credential’s scopes and restrictions. Zapier subscriptions use approved callback hosts supplied by Zapier.

Custom customer destinations remain unavailable until controlled outbound networking and destination ownership checks are enabled. Do not assume an arbitrary HTTPS URL is accepted. API entitlement, webhook entitlement and the bound credential are checked again before delivery.

Verify before processing

Use the Standard Webhooks library to check the signature against the exact raw request body before parsing it. Use the webhook-id, webhook-timestamp and webhook-signature headers with the signing secret. The library rejects timestamps more than five minutes from the current time. Process each immutable event ID once.

Preserve the raw body bytes; reserializing JSON changes what is signed. Rotation signs deliveries with the current and previous secrets for 24 hours. Replace the receiver’s secret during that period. A replay keeps its event ID and receives a new delivery timestamp.

import { Webhook } from 'standardwebhooks';

// rawBody is the original request body, not JSON.stringify(parsedBody).
const event = new Webhook(process.env.LINEBLINK_WEBHOOK_SECRET).verify(rawBody, {
  'webhook-id': request.headers.get('webhook-id'),
  'webhook-timestamp': request.headers.get('webhook-timestamp'),
  'webhook-signature': request.headers.get('webhook-signature'),
});
// Persist event.id in a unique store with your processing result before acknowledging.
await processOnce(event.id, event);

Handle retries and recovery

Delivery is at least once and can arrive out of order. Respond with 2xx after durably accepting the event, then run slow work separately. A 2xx confirms receipt; it does not mean a downstream automation finished.

Each attempt times out after 10 seconds. Network errors, 408, 429 and server errors retry for up to 24 hours or 32 attempts. Retries use exponential backoff with jitter, capped at one hour. Retry-After is bounded to one hour. Retry requests retain the logical event ID. A gone endpoint returning 410 is disabled. Inspect redacted delivery records before requesting a deliberate retry.

Access loss pauses delivery. Restoring plan access does not automatically replay the disabled period: explicitly resume the subscription to receive new events from its new high-water mark. Revoking or expiring the bound key stops its pushes.