Webhooks

Webhooks let Kerabie POST to your server whenever something happens: a new conversation, a message, a resolved ticket. Use them to sync with your CRM, trigger Slack alerts, or run any custom workflow.

Available on Starter, Pro, and Business plans.

Setup

Go to Settings → API & Webhooks → Webhooks
Click Add Endpoint
Enter your HTTPS URL (must be publicly reachable)
Select which events to receive
Save: copy the Webhook Secret shown once

Events

Event	When it fires
`conversation.created`	A visitor opens a new conversation
`conversation.resolved`	A conversation is marked resolved
`conversation.closed`	A conversation is closed
`message.sent.agent`	An agent sends a message
`message.sent.customer`	A visitor sends a message
`visitor.started`	A new visitor session begins
`visitor.page_view`	A visitor views a page (Pro)

Payload format

{
  "event": "message.sent.agent",
  "orgId": 42,
  "timestamp": "2026-05-26T14:32:00.000Z",
  "data": {
    "conversationId": 101,
    "messageId": 5231,
    "body": "Hi there! How can I help?",
    "agentId": 7,
    "agentName": "Sarah"
  }
}

Verifying the signature

Every request includes headers to confirm it came from Kerabie:

X-Kerabie-Event: message.sent.agent
X-Kerabie-Signature: sha256=abc123...
X-Kerabie-Timestamp: 1716733920

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

app.post('/webhooks/kerabie', express.raw({ type: 'application/json' }), (req, res) => {
  const valid = verifyWebhook(
    req.body,
    req.headers['x-kerabie-signature'],
    process.env.KERABIE_WEBHOOK_SECRET,
  );
  if (!valid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(req.body);
  // handle event.event, event.data ...
  res.json({ received: true });
});

import { KerAbieClient } from '@kerabie/sdk';

app.post('/webhooks/kerabie', express.raw({ type: 'application/json' }), (req, res) => {
  const isValid = KerAbieClient.webhooks.verify(
    req.body,
    req.headers['x-kerabie-signature'] as string,
    process.env.KERABIE_WEBHOOK_SECRET!,
  );
  if (!isValid) return res.status(401).send('Invalid signature');

  const event = KerAbieClient.webhooks.parse(req.body);
  console.log(event.event, event.data);
  res.json({ received: true });
});

Retry policy

If your endpoint returns non-2xx or times out (> 30 s), Kerabie retries automatically:

Attempt	Delay
1st retry	5 seconds
2nd retry	30 seconds
3rd retry	2 minutes
4th retry	10 minutes
5th retry	30 minutes

After 5 failures the delivery is marked failed. View logs in Settings → Webhooks → Delivery Logs.

Best practices

Respond 200 OK immediately, then process async (push to a queue).
Make your handler idempotent; the same event may arrive more than once.
Reject events whose timestamp is more than 5 minutes old to block replay attacks.