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

Source: https://talkdemo.com/help/integrations/webhooks · Updated 2026-11-20

## Key takeaways

- TalkDemo can send session.completed, lead.qualified and meeting.booked events to an https endpoint you own.
- Every request carries an X-TalkDemo-Signature header with a timestamp and an HMAC-SHA256 signature of the raw body.
- Verify the signature with your endpoint's secret and reject requests older than five minutes.
- Send test event checks your receiver at any time with a signed test.ping that carries no personal data.
- Failed deliveries are retried for about an hour and a half. Test console sessions never send webhooks.

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:

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

| Event | Sent when |
|---|---|
| `session.completed` | A demo has ended and its summary, score and outcome are ready (a minute or two after the call) |
| `lead.qualified` | The lead's score reached the qualified mark (60 of 100) when the demo ended |
| `meeting.booked` | A 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:

```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:

```text
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

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