Webhooks
Subscribe to chatbot events and integrate with external systems
Webhooks
Receive real-time notifications when events happen in your chatbots. Use webhooks to integrate with Zapier, Make, your CRM, or any external system.
Available Events
| Event | Fires When |
|---|---|
session.created | New conversation starts |
session.resolved | Conversation marked as resolved |
message.received | User sends a message |
message.sent | AI or agent sends a response |
lead.captured | User submits email/name via chatbot |
ticket.created | Support ticket created |
ticket.updated | Ticket status changed |
handoff.escalated | Conversation escalated to human |
handoff.assigned | Agent takes over conversation |
handoff.returned | Conversation returned to AI |
* | All events (wildcard) |
Creating a Webhook
POST /api/webhooks-config
Authorization: Bearer <clerk_token>
Content-Type: application/json
{
"url": "https://your-server.com/webhook",
"events": ["lead.captured", "session.created"],
"chatbotId": "optional_specific_chatbot_id"
}The response includes a signing secret (whsec_...) — save it, it's only shown once.
Payload Format
{
"event": "lead.captured",
"chatbotId": "cmf9n7u1c...",
"timestamp": "2026-03-26T15:30:00.000Z",
"data": {
"leadId": "clx...",
"name": "John Doe",
"email": "john@example.com",
"source": "lead-tool",
"sessionId": "rkt_abc123..."
}
}Verifying Signatures
Every webhook includes an X-RKT-Signature header with an HMAC-SHA256 signature:
const crypto = require('crypto');
function verifyWebhook(body, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(body)
.digest('hex');
return signature === expected;
}Reliability
- Timeout: 10 seconds per delivery
- Auto-disable: After 10 consecutive failures, the endpoint is deactivated
- Reset: Successful delivery resets the fail counter
- Re-enable: Toggle the endpoint back on from the dashboard after fixing issues
Managing Endpoints
| Method | Endpoint | Action |
|---|---|---|
GET | /api/webhooks-config | List all endpoints |
POST | /api/webhooks-config | Create new endpoint |
PATCH | /api/webhooks-config | Toggle active/inactive |
DELETE | /api/webhooks-config | Remove endpoint |
Last updated on