Skip to content

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

EventSent when
conversation.startedA customer starts a conversation
conversation.messageA customer sends a message (includes the text)
conversation.handed_overA conversation is handed to your team
conversation.closedA conversation is closed

Create a webhook

  1. In Settings → API & webhooks, select New webhook.
  2. Enter your endpoint's address. It must be https://.
  3. Choose the events to receive.
  4. Create it and copy the signing secret now; it is not shown again. It starts with whsec_.
  5. Send a test from the webhook's row. Your endpoint receives a ping event, 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:

json
{
  "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:

  1. 1Read t and v1 from the header
  2. 2Compute HMAC-SHA256 of t.rawBodywith your secret
  3. 3Compare with v1in constant time
  4. 4Reject if t is over 5 minutes old

In Node.js (Express):

js
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.

Something not working as described here? See Troubleshooting.

Get started free — 50 credits a month