Webhooks

How webhooks work

Register an https endpoint with POST /v1/webhooks and choose its events. NuTalk then POSTs each event as JSON, signed with the endpoint's secret. Endpoints are managed through the API (keys need webhooks:read or webhooks:write); test calls are never sent.

Conversation events carry customer messages, so * does not include them: name them in events, with a key that also has conversations:read. They are sent for the conversations the Conversations API lists (never test threads) and the customer's own messages (never reactions or internal notes).

Call events, and * which includes them, carry each call's numbers and outcome, so they take a key that also has calls:read.

Conversion events carry the workspace's conversions, so * does not include them either: name them, with a key that also has conversions:read, while Conversions is on for the workspace. Test events are never sent.

After the endpoints: the events, what each delivery carries and how to verify its signature.

Events

Each call sends each event at most once, whatever its phone line (a call that a late answer reopens keeps the events it already sent). Test calls and website widget sessions send none. For transcripts and summaries, fetch the call with GET /v1/calls/:call_id when the event arrives. A conversation event's data.conversation is read when the event is sent, so it can already show later changes; previous, current and the assignee ids describe the change itself.

An endpoint can listen to some campaigns only (campaign_ids when you create or update it): its call and campaign events are then only those of these campaigns, never a call outside every campaign. Conversation and conversion events carry no campaign and are sent as the endpoint subscribes to them. Changing the campaigns of an endpoint that receives call events takes calls:read, and an event already queued goes out only while its campaign is still one of them.

{
  "id": "evt_2c51d7e0-8f3a-4b6e-9a41-6f0d3e2b7c18",
  "event": "message.received",
  "created_at": "2026-10-02T12:15:09.120Z",
  "data": {
    "conversation": {
      "id": "5f0c2b1e-8d3a-4c6e-9b7f-2a4d6e8c0b13",
      "channel": {
        "id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
        "name": "Support WhatsApp",
        "type": "whatsapp"
      },
      "customer": {
        "name": "Ana",
        "handle": "5215512345678",
        "handle_type": "phone"
      },
      "contact": {
        "id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
        "name": "Ana López"
      },
      "status": "active",
      "archived": false,
      "assignee": null,
      "awaiting_reply": true,
      "…": "…"
    },
    "message": {
      "id": "0e6a4c2b-7f1d-4b3e-8a5c-9d2f4b6e8a10",
      "direction": "inbound",
      "sender": {
        "type": "customer",
        "user_id": null,
        "name": null
      },
      "text": "¿Siguen ahí?",
      "attachments": [],
      "created_at": "2026-10-02T12:15:08.634668+00:00",
      "stored_at": "2026-10-02T12:15:08.902115+00:00",
      "…": "…"
    }
  }
}

Delivery

Each delivery is a POST with these headers: Content-Type: application/json, User-Agent: NuTalk-Webhooks/1.0, X-NuTalk-Event (the event name) and X-NuTalk-Signature. The body:

{
  "id": "evt_6f3c9a2e-41b7-4f0e-9d8a-2c5b7e1f0a93",
  "event": "call.completed",
  "created_at": "2026-10-02T14:33:05.120Z",
  "data": {
    "call_id": "1ba11348-e440-44de-a5cd-5fe62f4d9df6",
    "status": "completed",
    "outcome": "answered",
    "direction": "outbound",
    "from_number": "+525512345678",
    "to_number": "+14155551234",
    "channel_id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
    "campaign_id": "c1a2b3c4-d5e6-4f70-8a91-b2c3d4e5f607",
    "campaign_enrollment_id": "7593112e-56ab-4a08-858f-21035eb1bacc",
    "started_at": "2026-10-02T14:29:40.000Z",
    "answered_at": "2026-10-02T14:29:48.000Z",
    "ended_at": "2026-10-02T14:32:40.000Z",
    "duration_seconds": 180,
    "credits_charged": 16,
    "credits_charged_exact": 16.5,
    "failure_reason": null,
    "failure_detail": null
  }
}

• credits_charged is a whole number of credits (the charge with its fraction dropped, never rounded up); credits_charged_exact is the exact charge, with up to 2 decimals. Prices are on the pricing page.
• Answer with a 2xx within 10 seconds; do the work afterwards. Redirects are not followed.
• A non-2xx answer, a timeout or a connection error is retried: up to 5 attempts in all, about 15 s, 30 s, 60 s and 2 min apart (deliveries run on a one-minute worker, so allow up to a minute more). After the fifth failure the event is dropped. A conversation event takes one more run of that worker first, to build its payload, so allow up to another minute for it.
• The same event can arrive more than once, and every attempt has a new id: deduplicate on event + data.call_id (one delivery per event, call and endpoint); for message.received on data.message.id, and for the other conversation events on data.change_id. Events can arrive in a different order than they happened.
• last_delivery_status on the endpoint shows the last result: http_200, http_500… or blocked:… when the URL points to a private address (never retried).
• Every attempt of the last 30 days is in the endpoint's delivery log, GET /v1/webhooks/:id/deliveries: the event, what it reports, which attempt it was, what your server answered and how long it took. For a conversion event, deduplicate on data.change_id.

Verify the signature

X-NuTalk-Signature looks like t=1790911190123,v1=5f8c…: t is the send time in Unix milliseconds and v1 is the hex HMAC-SHA256 of `${t}.${rawBody}` with the endpoint's secret. Compute it over the raw body (before parsing JSON), compare in constant time, and reject old timestamps.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string, before JSON.parse).
// header: the X-NuTalk-Signature header. secret: the whsec_… from POST /v1/webhooks.
export function verifyNutalkSignature(rawBody, header, secret, toleranceMs = 5 * 60 * 1000) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((part) => part.split("=", 2))
  );
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() - timestamp) > toleranceMs) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const given = Buffer.from(parts.v1 || "", "hex");
  const wanted = Buffer.from(expected, "hex");
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}

In an Express server, keep the raw body for the check:

import express from "express";
import { verifyNutalkSignature } from "./verify-nutalk-signature.js";

const app = express();

// Keep the raw body: the signature covers the exact bytes NuTalk sent.
app.post("/webhooks/nutalk", express.text({ type: "application/json" }), (req, res) => {
  const ok = verifyNutalkSignature(
    req.body,
    req.get("X-NuTalk-Signature"),
    process.env.NUTALK_WEBHOOK_SECRET
  );
  if (!ok) return res.status(401).send("Invalid signature");

  const event = JSON.parse(req.body);
  // A delivery can arrive more than once, each attempt with a new event.id:
  // deduplicate on event.event + event.data.call_id.
  console.log(event.event, event.data.call_id);
  res.status(200).send("ok"); // answer within 10 seconds
});