Webhooks

DialogBrain sends HTTP POST requests to your URL when events occur in your account.

Setup

1. Go to Settings → Developer → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL
4. Select the event types you want to receive
5. Copy the whsec_ secret — shown only once

Event Types

Event	When it fires
message.received	New inbound message in any channel
message.updated	Message edited
message.deleted	Message deleted
conversation.started	New conversation thread created
conversation.updated	Thread metadata changed (title, assignment, etc.)
conversation.closed	Thread marked as closed
handoff.requested	AI requested human takeover
draft.created	Auto-reply draft created, awaiting approval
contact.updated	Contact profile updated

Payload Format

{
  "event": "message.received",
  "delivery_id": "12345",
  "data": {
    "thread_id": "telegram:123456789",
    "message_id": "987654321",
    "channel": "telegram",
    "text": "Hello!",
    "from": { "id": "123456789", "name": "Alice" },
    "timestamp": "2026-03-11T10:00:00Z"
  }
}

Retries

Failed deliveries are retried 5 times: after 5s, 10s, 20s, 40s, and 80s. After 3 consecutive delivery failures, the webhook is auto-deactivated. Re-activate it from Settings after fixing your endpoint.

Security

Every request includes an X-DialogBrain-Signature header. See Verification.