Agency & Reseller

Outbound Webhooks

Receive signed HTTP notifications when events happen in your client workspaces, like a captured lead or a handoff request.

Webhooks let your systems react to platform events without polling. When an event happens in one of your client workspaces, AI Chatbot sends a signed POST request to your endpoint.

Manage endpoints under Agency > Webhooks in your dashboard, or via the Agency API.

Events

Event

Fires when

lead.captured

A visitor leaves contact details in a client workspace’s AI agent

escalation.created

A visitor asks to talk to a human

client.credits_exhausted

A client workspace runs out of message credits (monthly limit plus any top-up credits)

ping

You send a test from the dashboard or API

Each endpoint can subscribe to specific events or receive all of them. Endpoints subscribed to all events also receive event types added in the future.

Behaviors to know:

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 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, null is in the payload.

Payload

Every request body has the same envelope:

				
					{
  "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_exhaustedcarries message_limit, messages_used, and topup_credits_remaining.

Auto-replenish flow

client.credits_exhausted pairs with the Add Top-Up Credits endpoint to automate replenishment: when the event arrives, charge the client in your own billing system, then call the top-ups API. Use the event’s delivery id as your Idempotency-Key so a retried delivery can never buy credits twice. The client’s AI agents start answering again within seconds of the top-up.

Verifying signatures

Every request includes these headers:

Header

Value

X-Signature-256

sha256= followed by an HMAC SHA-256 of the raw request body, keyed with your webhook secret

X-Webhook-Event

The event type

cX-Delivery-Id

The delivery id (same as id in the body)

Your webhook secret is shown once when you create the endpoint. Verify each request by computing the HMAC over the raw body and comparing:

				
					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);
}

Reject requests with a missing or invalid signature.

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.

Use the Test button in the dashboard (or the test endpoint) to send a signed ping event and confirm your endpoint and signature verification work end to end.

Ready to automate your customer service with AI?

Join over 1000+ businesses, websites and startups automating their customer service and other tasks with a custom trained AI agent.

API & Tools