logoRocketFlow

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

EventFires When
session.createdNew conversation starts
session.resolvedConversation marked as resolved
message.receivedUser sends a message
message.sentAI or agent sends a response
lead.capturedUser submits email/name via chatbot
ticket.createdSupport ticket created
ticket.updatedTicket status changed
handoff.escalatedConversation escalated to human
handoff.assignedAgent takes over conversation
handoff.returnedConversation 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

MethodEndpointAction
GET/api/webhooks-configList all endpoints
POST/api/webhooks-configCreate new endpoint
PATCH/api/webhooks-configToggle active/inactive
DELETE/api/webhooks-configRemove endpoint

Last updated on