Skip to content
TalkDemo
Integrations

Receive webhooks and verify signatures

Send session.completed, lead.qualified and meeting.booked events to your own endpoint, and verify each request with the X-TalkDemo-Signature header.

Webhooks send TalkDemo events to your own systems as they happen, so you can update a data warehouse, a CRM TalkDemo does not connect to, or an internal tool.

Who can do this: Admin. Members see the list of endpoints; Viewers see only each endpoint's host.

Add an endpoint

  1. Open Integrations and choose Webhooks in the side menu.
  2. Click Add endpoint and enter an https URL on a public host in Endpoint URL.
  3. Choose the events: session.completed, lead.qualified, meeting.booked. All three are ticked to start with.
  4. Click Add webhook. Copy the signing secret from Copy your signing secret: it is shown once. Click I've stored it.

A workspace can have up to 10 endpoints. Each one has an On switch, so you can pause it without deleting it.

Send a test event

Click Send test event on an endpoint to check your receiver. TalkDemo sends one signed test.ping request, the same way it sends real events, whatever events the endpoint is subscribed to. A few seconds later the endpoint's row shows the result as Last sent with the HTTP status your server answered, or no response when the address couldn't be reached.

  • The endpoint must be switched On.
  • A test is tried once, with no retries.
  • You can send 5 test events to an endpoint every 10 minutes.

The test body carries no session, lead or personal data:

{
  "id": "evt_test_ping_…",
  "type": "test.ping",
  "created": "2026-11-19T16:22:03.065Z",
  "workspaceId": "…",
  "test": true,
  "data": { "message": "Test event from TalkDemo. It carries no session or lead data." }
}

Its X-TalkDemo-Event header is test.ping. Verify its signature like any other request, then ignore it or answer 200.

The events

EventSent when
session.completedA demo has ended and its summary, score and outcome are ready (a minute or two after the call)
lead.qualifiedThe lead's score reached the qualified mark (60 of 100) when the demo ended
meeting.bookedA meeting was really booked: the agent booked a time on your calendar during the call, or the prospect booked from the demo's Cal.com or Calendly link. Showing the booking link alone doesn't send it

Each event is sent once per endpoint. Test console sessions never send events. lead.role is the prospect's role from the start screen or link, or their answer to a role question (key role or job_title, or a question labelled "Role" or "Job title").

The body is JSON:

{
  "id": "evt_session_completed_…",
  "type": "session.completed",
  "created": "2026-11-19T16:22:03.065Z",
  "workspaceId": "…",
  "data": {
    "session": { "id": "…", "agentId": "…", "channel": "LINK", "mode": "LIVE_PRODUCT", "language": "en-IN", "status": "ENDED", "outcome": "MEETING_BOOKED", "score": 90, "summary": "…", "engaged": true, "durationSec": 193, "startedAt": "…", "endedAt": "…", "prospect": { "name": "…", "company": null, "role": null } },
    "lead": { "id": "…", "sessionId": "…", "agentId": "…", "status": "MEETING_BOOKED", "score": 90, "name": "…", "company": null, "role": null, "email": "…", "phone": null, "answers": { "team_size": "51 to 200" }, "meetingAt": null, "createdAt": "…" }
  }
}

lead.qualified and meeting.booked carry only data.lead. answers is keyed by your qualification question keys. Requests also carry X-TalkDemo-Event (the event type) and X-TalkDemo-Delivery (the same as the body's id).

The signature header

Each request has this header:

X-TalkDemo-Signature: t=1763539200,v1=5f2b0c...
  • t is the Unix time in seconds when TalkDemo signed the request.
  • v1 is the hex HMAC-SHA256 of the string t, a full stop, then the raw request body, using your signing secret.

To verify:

  1. Read the raw body before any JSON parsing.
  2. Split the header into t and v1.
  3. Reject the request if t is more than five minutes from your clock.
  4. Compute the HMAC of t.body and compare it with v1 in constant time.

Node example

import crypto from "node:crypto";

export function verifyTalkDemo(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (Number.isNaN(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

// Express: keep the body raw for this route.
// app.post("/talkdemo", express.raw({ type: "application/json" }), (req, res) => {
//   const ok = verifyTalkDemo(req.body.toString("utf8"), req.get("X-TalkDemo-Signature") ?? "", process.env.TALKDEMO_SECRET);
//   res.sendStatus(ok ? 200 : 400);
// });

Delivery and retries

Answer within 10 seconds with a 2xx status, and do slow work after you reply. Anything else, including a redirect, is retried with growing gaps (1, 2, 4 minutes and so on, up to 15 minutes apart), 8 tries in all, about an hour and a half. The endpoint list shows the last status and time. A retry has the same id and X-TalkDemo-Delivery: use it to ignore duplicates.

Privacy

Event bodies include prospect details such as name, company and answers, and contact details when they were collected. Keep your endpoint on https, verify every signature, and apply your own retention to what you store.

Frequently asked questions

Can I send webhooks to a private network address?

No. Endpoints must be public https hosts.

How do I rotate the secret?

Click the key button on the endpoint (Rotate signing secret), then Rotate secret. The new secret is shown once and the old one stops working at once, so update your server straight away. Requests are signed with the new secret from then on.

ShareXLinkedIn Email

View as Markdown

Something unclear or missing? Tell us