Skip to main content

Webhooks

DialogBrain sends HTTP POST requests to your webhook URL when events occur. Every subscription receives events for your workspace.

Creating a Subscription​

Subscribe to events via POST /api/v1/webhooks:

{
  "url": "https://example.com/webhooks",
  "event_types": ["message.received", "message.updated"]
}

The response includes a secret — shown only once. Use it to verify webhook signatures.

Payload Format​

Every delivery is a POST request with this JSON body:

{
  "event": "message.received",
  "delivery_id": "18273",
  "data": {
    ...
  }
}

The event name and data shape for each event type are documented on the Events page.

Retries​

Failed deliveries are retried 5 times with exponential backoff: after 5s, 10s, 20s, 40s, and 80s.

After repeated consecutive failures, the subscription is paused. Re-enable it by calling the activate endpoint.

Listing Deliveries​

Query delivery status per subscription via the API; delivery IDs and timestamps are included for tracking and reconciliation.

Security​

Every delivery includes an X-DialogBrain-Signature header signed with your subscription's secret. Verify the signature to confirm the request came from DialogBrain.