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
| Event | When it is sent |
|---|---|
item.updated | Every time an item changes status or result |
message.status | The 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.closed | A conversation with items is closed; reason says how: resolved_by_ai, closed_by_agent, auto_timeout or agent_inactivity |
conversation.handoff | A conversation with items is handed to a person on the team (it is not closed) |
integration.ping | When 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": []
}
}
}
- In
item.updated,data.itemis the full item, the same as inGET /v1/items/{type}/{external_id}(the example shows it trimmed), anddata.item_eventsays what changed in that event and who did it (agent,api,userorsystem). - In
integration.ping,datais{ "message": "ping" }and the item fields arenull.
Headers
| Header | What it carries |
|---|---|
X-TalkAI-Event-Id | The same event_id as the body |
X-TalkAI-Event | The event name |
X-TalkAI-Timestamp | Seconds since 1970 (epoch) at the time of the attempt |
X-TalkAI-Signature | sha256=<hex> with the current secret |
X-TalkAI-Signature-Key-Id | The id of the secret used to sign (the panel shows it as Current secret id) |
X-TalkAI-Signature-Previous | For 24 h after a rotation: the signature with the previous secret |
X-TalkAI-Signature-Previous-Key-Id | The id of the previous secret |
Authorization | Bearer <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.
X-TalkAI-Timestamp and X-TalkAI-Signature headers.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).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
- Only a 2xx response counts as delivered. Any other code, a timeout (8 seconds) or a network error is retried.
- Redirects are not followed: a 301 or 302 counts as a failure. Register the final URL.
- Retries happen at 1, 5, 15 and 60 minutes; if the last attempt fails too, the notification is marked as failed. To recover it, call
GET /v1/items?updated_since=. - Notifications do not necessarily arrive in order. Use the item's
updated_atto keep the newest state. - The same notification can arrive more than once (for example, if your system processed it but was slow to answer). Every attempt carries the same
event_id: store it and discard duplicates. - If the organization loses integrations, notifications are paused and go out when they are re-enabled.
https. Internal or private addresses are not accepted.