Webhooks

Get notified in real-time when events happen in Bancroft.

Events

Name	Type	Description
`conversation.created`	event	A new conversation was created
`conversation.resolved`	event	A conversation was resolved/closed
`conversation.assigned`	event	A conversation was assigned to an agent
`message.created`	event	A new message was sent in a conversation
`callback.requested`	event	A callback was requested via the support widget

Payload Format

All webhook payloads are JSON with a consistent structure:

json

{
  "event": "message.created",
  "conversation": {
    "id": "a1b2c3d4-...",
    "number": 42,
    "subject": "Help with order #1234",
    "status": "open",
    "requester_email": "customer@example.com",
    "channel": "web",
    "metadata": {}
  },
  "message_id": "m1-uuid",
  "message_type": "reply"
}

Callback Requested

When a conversation is created with channel: "callback", an additional callback.requested event is fired alongside conversation.created.

json

{
  "event": "callback.requested",
  "conversation": {
    "id": "a1b2c3d4-...",
    "number": 43,
    "subject": "Callback request from Jane",
    "status": "open",
    "requester_email": "jane@example.com",
    "channel": "callback",
    "metadata": {
      "phone": "+1-555-1234",
      "preferred_time": "Afternoons EST"
    }
  }
}

Signature Verification

Every webhook request includes an X-Bancroft-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with your webhook secret. Always verify this before processing.

python

import hashlib
import hmac

def verify_webhook(payload_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Headers

Name	Type	Description
`X-Bancroft-Signature`	string	HMAC-SHA256 hex digest of the request body
`X-Bancroft-Event`	string	The event type (e.g., message.created)
`Content-Type`	string	Always application/json

Retry Policy

Failed deliveries (non-2xx responses or timeouts) are retried with exponential backoff:

Attempt 2: after 1 minute
Attempt 3: after 5 minutes
Attempt 4: after 30 minutes
Attempt 5: after 2 hours
Attempt 6: after 6 hours

After 6 failed attempts, the delivery is marked as failed. You can view delivery logs in the dashboard under Settings → Integrations → Webhooks.

Managing Webhooks

Create and manage webhook endpoints from your dashboard or via the management API (requires admin session auth):

bash

curl -X POST https://your-domain.com/api/integrations/webhooks/create/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=..." \
  -d '{
    "url": "https://api.mydomain.com/webhooks/bancroft",
    "events": ["message.created", "conversation.resolved"]
  }'

Loading…