Outbound Webhooks

​

Events

• lead.captured fires the first time a visitor leaves contact details. Repeat submissions and identify calls for the same visitor do not fire it again.
• A handoff request that includes contact details fires escalation.created only, not both events. The escalation payload carries the same visitor contact fields.
• client.credits_exhausted fires once per exhaustion: it does not repeat while the client stays at zero, and it arms again once credits return (a top-up, a limit raise, or the monthly renewal). It only fires for clients with their own message_limit, and only when their own budget runs out, not when your agency-wide pool does. Since it is a team-level event, chatbot_id is null in the payload.

​

Payload

{
  "id": "9194bb86-10ab-443c-829c-5c420c475e2f",
  "event": "lead.captured",
  "timestamp": "2026-08-18T11:43:08+00:00",
  "team_id": "8e7a1b4c-8c7c-4029-aa4e-c3bf3c8b7abc",
  "external_reference": "your-billing-id-123",
  "chatbot_id": "8cc9fd44-4c7c-4d5d-aebe-68b03e8236fd",
  "data": {
    "visitor": {
      "id": "a176e7eb-c8bb-4be0-bc1a-608f4377df8d",
      "visitor_id": "wh-visitor-1",
      "email": "customer@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": null,
      "custom_data": { "company": "Acme Co" }
    },
    "chatbot_name": "Support Agent"
  }
}

• id is unique per delivery and stays the same across retries, so you can deduplicate.
• team_id is the client workspace the event happened in.
• external_reference is the billing reference you set on the client workspace, so you can map events straight to your own billing system.
• data is event-specific. escalation.created adds last_message and inbox_url. client.credits_exhausted carries message_limit, messages_used, and topup_credits_remaining.

​

Auto-replenish flow

​

Verifying signatures

const crypto = require("crypto")

function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
  const received = Buffer.from(signatureHeader ?? "")
  const expectedBuffer = Buffer.from(expected)

  // timingSafeEqual throws on length mismatch, so check length first.
  return (
    received.length === expectedBuffer.length &&
    crypto.timingSafeEqual(received, expectedBuffer)
  )
}

function verify(string $rawBody, ?string $signatureHeader, string $secret): bool
{
    if ($signatureHeader === null) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

    return hash_equals($expected, $signatureHeader);
}

​

Delivery and retries

• Respond with any 2xx status within 15 seconds to acknowledge a delivery. Redirects are not followed.
• A failed delivery is attempted up to 5 times in total: the initial delivery plus 4 retries after 30 seconds, 2 minutes, 10 minutes, and 1 hour. A delivery that exhausts its attempts gets a last error ending in (retries exhausted).
• The last 30 days of delivery attempts are visible under Agency > Webhooks and via the deliveries endpoint, including response status and the last error.
• To change an endpoint’s URL or event subscriptions, use the update endpoint; the signing secret stays the same. Deleting and recreating an endpoint generates a new secret.