Webhooks

Webhooks push events from ROLLER to your endpoint as they happen, so your marketplace stays in sync without polling.

Webhook topics and events

Message envelope

Every delivery has this shape:

{
  "id": "8b6e7f64-9da2-4c3e-b1a4-0a4f7b6f2d11",
  "sendDate": "2026-06-11T03:21:09Z",
  "type": "Booking",
  "eventDate": "2026-06-11T03:21:08Z",
  "eventType": "Updated",
  "data": { /* topic-specific payload */ }
}

Configuring webhooks

Create a webhook with POST /webhooks (scope: Webhook_Create). Each configuration takes a target url, optional authentication, and per-topic event subscriptions with filters:

• Booking — filter by sales channels, product types, product IDs or product category; optionally include tickets, payments, costs, locations, membership detail, customer flags and external IDs in the payload
• Redemption — filter by product IDs/category; optionally include membership and multi-pass detail
• Product — filter by product types
• Customer — optionally include customer flags

Securing your endpoint

Configure authentication on the webhook so you can verify deliveries:

• API key — ROLLER sends your nominated key with each delivery
• Basic auth — username/password
• Signature — enable the signature inclusion to verify message integrity

Always respond 2xx quickly (queue work for async processing). Non-2xx responses trigger retries.

Delivery, retries and recovery

Failed deliveries are retried up to 7 times with backoff. To monitor and recover:

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0052FF', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0A1128', 'lineColor': '#0052FF', 'secondaryColor': '#E8F0FE', 'tertiaryColor': '#E8F0FE', 'mainBkg': '#0052FF', 'clusterBkg': '#E8F0FE', 'edgeLabelBackground': '#0A1128', 'fontFamily': 'Montserrat, sans-serif', 'fontSize': '14px', 'actorBkg': '#0A1128', 'actorBorder': '#0052FF', 'actorTextColor': '#ffffff', 'actorLineColor': '#0A1128', 'signalColor': '#0052FF', 'signalTextColor': '#0052FF', 'labelBoxBkgColor': '#E8F0FE', 'labelTextColor': '#0A1128', 'loopTextColor': '#0052FF', 'noteBkgColor': '#E8F0FE', 'noteTextColor': '#0A1128', 'noteBorderColor': '#0052FF', 'activationBorderColor': '#FF3B30', 'activationBkgColor': '#E8F0FE'}, 'themeCSS': '.node rect, .cluster rect, rect.actor { rx: 10px; ry: 10px; } .labelBox, .note { rx: 8px; ry: 8px; } .edgeLabel rect, .activation0, .activation1, .activation2 { rx: 4px; ry: 4px; } .nodeLabel, .edgeLabel, .label, .cluster-label, text, tspan, span, p { font-family: Montserrat, sans-serif; }'}}%%
flowchart TD
    A["Event occurs in ROLLER<br/>Booking, Ticket, Product, etc."] --> B["ROLLER sends webhook<br/>POST to your endpoint"]
    B --> C{Response<br/>2xx?}
    C -->|Yes| D["✓ Delivered<br/>Event processed"]
    C -->|No| E["Delivery failed<br/>Record HTTP status"]
    E --> F["Queue for retry<br/>with exponential backoff"]
    F --> G{Retries<br/>remaining?}
    G -->|Yes| H{Wait &<br/>retry}
    H -->|After backoff delay| B
    G -->|No| I["❌ Max retries exceeded<br/>7 failed attempts"]
    I --> J["Call GET /webhooks/messages/failed<br/>to list failed messages"]
    J --> K["Reconcile gaps by<br/>re-fetching entities"]

1. Call GET /webhooks/messages/failed (scope: Webhook_GetFailedMessages) to list recently failed messages, including per-attempt HTTP status, failure detail, and nextRetryDate.
2. Reconcile gaps by re-fetching the affected entities (GET /bookings/{uniqueId}, etc.).

See the webhook event processing recipe for an end-to-end implementation.