Webhooks: signed notifications

Who it's for: developers of the system that receives TalkAI notifications

What it's for

Every time an item changes, TalkAI sends a POST to the URL you registered in Settings > Integrations > Webhook. That way your system learns right away that a customer confirmed, cancelled or asked for a change, without having to ask.

Events

EventWhen it is sent
item.updatedEvery time an item changes status or result
message.statusThe status of a message in a conversation with items changes, including the campaign's initial template: sent, delivered, read or failed (with the WhatsApp error code)
conversation.closedA conversation with items is closed; reason says how: resolved_by_ai, closed_by_agent, auto_timeout or agent_inactivity
conversation.handoffA conversation with items is handed to a person on the team (it is not closed)
integration.pingWhen you click Test webhook in the panel (it does not need to be ticked in the events; the webhook must be active)

The three message and conversation events carry item_external_ids with the items involved. Conversations without items do not generate notifications.

If the contact sends files, item.updated carries in item_event.attachments only the new attachments of that change, each with its sha256 and a link that expires after 24 h. If the link expired, read the item: every read returns fresh links.

If the webhook is off or has no URL, notifications are not stored for later: use GET /v1/items?updated_since= to catch up (see API reference).

The body

All events share the same envelope:

{
  "event_id": "3b6f0c1e-...",
  "event": "item.updated",
  "occurred_at": "2026-11-19T12:06:42.120Z",
  "flow": "confirmar_pedidos",
  "campaign_id": "6f1c...",
  "campaign_external_id": "camp-2026-11-20",
  "conversation_id": "9a2e...",
  "contact_external_id": "cliente-77",
  "item_type": "pedido",
  "item_external_id": "P-1001",
  "data": {
    "item": { "type": "pedido", "external_id": "P-1001", "status": "resolved", "result": { "respuesta": "confirma" } },
    "item_event": {
      "type": "status_changed",
      "actor": { "type": "agent", "id": "..." },
      "from_status": "in_progress",
      "to_status": "resolved",
      "result_diff": { "respuesta": { "from": null, "to": "confirma" } },
      "motivo": null,
      "attachments": []
    }
  }
}

Headers

HeaderWhat it carries
X-TalkAI-Event-IdThe same event_id as the body
X-TalkAI-EventThe event name
X-TalkAI-TimestampSeconds since 1970 (epoch) at the time of the attempt
X-TalkAI-Signaturesha256=<hex> with the current secret
X-TalkAI-Signature-Key-IdThe id of the secret used to sign (the panel shows it as Current secret id)
X-TalkAI-Signature-PreviousFor 24 h after a rotation: the signature with the previous secret
X-TalkAI-Signature-Previous-Key-IdThe id of the previous secret
AuthorizationBearer <your token>, only if you set it in the panel

Content-Type: application/json and User-Agent: TalkAI-Webhooks/1 are sent too.

Verify the signature

The signature is an HMAC-SHA256, keyed with your whsec_... secret, of the string "<timestamp>.<body>": the value of X-TalkAI-Timestamp, a dot and the body exactly as received, byte for byte. Compute it over the raw body, before parsing the JSON: if you parse it and serialize it again, the signature will not match.

➡️
Step:Read the raw body and the X-TalkAI-Timestamp and X-TalkAI-Signature headers.
➡️
Step:Reject the notification if the timestamp is more than 5 minutes away from your clock (it protects against replays of old notifications).
➡️
Step:Compute sha256= + the hex HMAC-SHA256 of timestamp + "." + body with your secret and compare it with X-TalkAI-Signature in constant time. If it does not match and X-TalkAI-Signature-Previous arrived, try that one (with your previous secret).
➡️
Step:If the signature is valid, answer 2xx quickly and process the notification afterwards.

Example in Node.js with Express:

const crypto = require('crypto');
const express = require('express');

const app = express();
const SECRET = process.env.TALKAI_WEBHOOK_SECRET; // whsec_...
const processed = new Set(); // in your system, a table of event_id

function validSignature(rawBody, ts, signature, secret) {
  if (!signature || !secret) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/talkai', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const ts = req.get('X-TalkAI-Timestamp');
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(400).end();

  const ok = validSignature(rawBody, ts, req.get('X-TalkAI-Signature'), SECRET)
    || validSignature(rawBody, ts, req.get('X-TalkAI-Signature-Previous'), process.env.TALKAI_WEBHOOK_SECRET_PREVIOUS);
  if (!ok) return res.status(401).end();

  const event = JSON.parse(rawBody);
  if (processed.has(event.event_id)) return res.status(200).end(); // duplicate: we already have it
  processed.add(event.event_id);

  res.status(200).end(); // answer first, process afterwards
  if (event.event === 'item.updated') {
    const item = event.data.item;
    console.log(item.type, item.external_id, item.status, item.result);
  }
});

app.listen(3000);

Rotate the secret

From the panel, Rotate secret generates a new one and shows it only once. For the next 24 h every notification is signed with the new one in X-TalkAI-Signature and with the previous one in X-TalkAI-Signature-Previous, so you can update your system without losing notifications. After 24 h, only the new one is valid. The first time, the secret is generated automatically when you save the webhook with its URL.

Delivery and retries

⚠️
Warning:The URL must be public and use https. Internal or private addresses are not accepted.