Skip to main content

​
Webhooks

Receive real-time HTTP callbacks when events occur in your Char AI integration.

​
Supported Events

EventDescription
conversation.startedNew conversation initiated
conversation.endedConversation marked complete
message.createdNew message in conversation
user.createdNew end user registered
skill.executedCustom skill was triggered

​
Setting Up Webhooks

1

Create Endpoint

Create an HTTP endpoint in your application to receive webhook payloads:
app.post('/webhooks/char', (req, res) => {
  const event = req.body;
  console.log('Received event:', event.type);
  res.status(200).send('OK');
});
2

Configure in Dashboard

Navigate to Settings > Webhooks and add your endpoint URL.
3

Select Events

Choose which events should trigger the webhook.
4

Verify Signature

Validate the webhook signature to ensure authenticity.

​
Payload Format

{
  "id": "evt_123abc",
  "type": "message.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "conversation_id": "conv_456def",
    "message": {
      "role": "user",
      "content": "Hello, I need help"
    }
  }
}

​
Signature Verification

Verify webhook authenticity using the signature header: 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

​
Retry Policy

Failed webhook deliveries are retried:
  • Attempt 1: Immediate
  • Attempt 2: After 1 minute
  • Attempt 3: After 5 minutes
  • Attempt 4: After 30 minutes
  • Attempt 5: After 2 hours
Webhooks that fail all retry attempts are marked as failed and logged in your dashboard.