Webhooks
Hear about conversations as they happen, and verify that each call came from us.
On this page
Webhooks tell your systems what happens in your conversations, as it happens. Use them to post a Slack alert when a customer asks for a person, create a CRM record when a conversation starts, or log every closed conversation. Like the API, they are available on paid plans.
Events
| Event | Sent when |
|---|---|
conversation.started | A customer starts a conversation |
conversation.message | A customer sends a message (includes the text) |
conversation.handed_over | A conversation is handed to your team |
conversation.closed | A conversation is closed |
Create a webhook
- In Settings → API & webhooks, select New webhook.
- Enter your endpoint's address. It must be
https://. - Choose the events to receive.
- Create it and copy the signing secret now; it is not shown again. It starts with
whsec_. - Send a test from the webhook's row. Your endpoint receives a
pingevent, and the delivery log shows the result.
You can pause, resume, change the events of, or delete a webhook at any time.
What we send
A POST with a JSON body:
{
"id": "0199…",
"event": "conversation.message",
"createdAt": "2026-10-09T10:15:00.000Z",
"data": {
"conversationId": "…",
"agentId": "…",
"channel": "widget",
"status": "new",
"contactId": null,
"message": { "id": "…", "content": "Where is my order?", "createdAt": "…" }
}
}
message is filled only for conversation.message. id is the delivery's id and stays the same on every retry. Store the ids you have handled and ignore repeats.
Verify the signature
Anyone can send a request to your endpoint, so check that it came from us before trusting it. Every request carries a header:
x-ikazebot-signature: t=1760004900,v1=5f2c…
v1 is the HMAC-SHA256, made with your signing secret, of <t>.<raw body>. To verify:
- 1Read t and v1 from the header
- 2Compute HMAC-SHA256 of t.rawBodywith your secret
- 3Compare with v1in constant time
- 4Reject if t is over 5 minutes old
In Node.js (Express):
import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';
const app = express();
// Use the RAW body: re-serialised JSON will not match the signature.
app.post('/ikazebot', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('x-ikazebot-signature') ?? '';
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const t = Number(parts.t);
const expected = createHmac('sha256', process.env.IKAZEBOT_WEBHOOK_SECRET)
.update(`${t}.${req.body}`)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - t) < 300;
const valid =
typeof parts.v1 === 'string' &&
parts.v1.length === expected.length &&
timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
if (!fresh || !valid) return res.sendStatus(400);
const event = JSON.parse(req.body);
// … handle event.event, ignoring an event.id you have already handled …
res.sendStatus(200);
});
The timestamp check stops someone replaying an old request at you.
Delivery and retries
- Reply with any 2xx status within 10 seconds to acknowledge. Do slow work afterwards, for example in a queue.
- Anything else is retried 7 times over about 30 minutes, then marked failed.
- Each webhook's delivery log shows every attempt from the last 30 days: status, attempts, the last HTTP code and error.
Related
Something not working as described here? See Troubleshooting.