Webhooks let your systems react when events happen in Chatzuri. A new lead lands? A conversation starts? A customer thumbs-down a reply? Subscribe and your endpoint gets pinged.
Subscribing
On any agent, Settings → Webhooks:
- Click + New webhook
- Enter your endpoint URL
- Pick the events you want to subscribe to
- (Optional) set a signing secret
- Click Save
Available events
lead.submit— a customer's lead form was capturedmessage.received— a customer sent a messagemessage.sent— your agent sent a replyconversation.started— a new conversation beganconversation.ended— a conversation closedfeedback.submitted— a customer rated a replyescalation.triggered— an escalation action fired
Payload format
POST your-endpoint
Content-Type: application/json
X-Chatzuri-Signature: sha256=<hmac>
{
"event": "lead.submit",
"timestamp": "2026-04-26T08:30:14Z",
"agent_id": "agt_abc123",
"data": {
"name": "Sarah",
"email": "sarah@acme.com",
"phone": "+254712345678",
"channel": "website"
}
}Verifying signatures
If you set a signing secret, every request includes an X-Chatzuri-Signature header. Compute the HMAC-SHA256 of the raw body using your secret and compare. See the full code examples in the webhooks API docs.
Tip
Always verify signatures in production. Webhook URLs leak more often than you'd think — a signature check turns a leaked URL into a non-issue.
Retries
If your endpoint returns a non-2xx, Chatzuri retries with exponential backoff for up to 24 hours. After that, the event is dropped (but logged in the agent's webhook delivery log).
Outbound (custom actions) vs inbound (webhooks)
- Outbound — agent → your system. Use a custom action.
- Inbound — Chatzuri → your system on events. Use this guide.