# Signed webhooks

> Receive WhatSetter events on your server the moment they happen, verify the HMAC-SHA256 signature in Node.js, Python or PHP, and test your endpoint.

Source: https://docs.whatsetter.com/developers/webhooks/

Instead of polling the API in a loop, let WhatSetter **push** events to your server the moment they happen. Every delivery is signed, so you can be sure it comes from us.

## The events

| Event | Fired when | Status |
|---|---|---|
| `contact.qualified` | The agent qualifies a lead (your prompt's criteria) | Live |
| `contact.not_qualified` | The agent rules a lead out | Live |
| `agent.disconnected` | A WhatsApp number disconnects | Live |
| `booking.created` | Your agent books a meeting in the conversation | Live |
| `message.received` | A lead sends a message to one of your agents | Live |

> **`message.received` is high volume**
It is sent for every message a lead writes to your agents. Subscribe to it only if your server needs each message.

> **A label the agent puts: `contact.label_added`**
It does not come from a subscription. It goes to the webhook URLs set in an agent's **Hand-off & alerts**, for the labels chosen there. See [Webhooks set on an agent](#webhooks-set-on-an-agent).

## Create a subscription

[POST /webhooks](/api-reference/operations/createwebhook/) needs the `webhooks:manage` scope. The URL must be a public HTTPS address: `localhost`, private networks and reserved addresses are refused.

**cURL**

```bash
curl -X POST https://app.whatsetter.com/api/v1/webhooks \
  -H "Authorization: Bearer $WHATSETTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-server.com/webhooks/whatsetter","events":["contact.qualified","contact.not_qualified"],"description":"CRM sync"}'
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-server.com/webhooks/whatsetter',
    events: ['contact.qualified', 'contact.not_qualified'],
    description: 'CRM sync',
  }),
});
const { data } = await res.json();
console.log(data.secret); // whsec_… shown once, store it now
```

**Python**

```python
import os, requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
    json={
        "url": "https://your-server.com/webhooks/whatsetter",
        "events": ["contact.qualified", "contact.not_qualified"],
        "description": "CRM sync",
    },
)
print(r.json()["data"]["secret"])  # whsec_… shown once, store it now
```

```json
{
  "data": {
    "id": "66f1c0ffee00000000000abc",
    "url": "https://your-server.com/webhooks/whatsetter",
    "events": ["contact.qualified", "contact.not_qualified"],
    "active": true,
    "description": "CRM sync",
    "secret_prefix": "whsec_3f9a",
    "secret": "whsec_3f9a…",
    "last_delivery_at": null,
    "last_delivery_status": null,
    "created_at": "2026-09-19T10:00:00.000Z"
  }
}
```

The response contains the **signing secret** (`whsec_…`). It is shown only here: store it immediately. Later calls to [GET /webhooks](/api-reference/operations/listwebhooks/) only return `secret_prefix`.

Errors that matter:

| HTTP | `code` | Why |
|---|---|---|
| 422 | `validation_error` | Missing or non-HTTPS `url`, empty or unknown `events`, `description` longer than 255 characters. |
| 429 | `quota_exceeded` | The workspace already has 10 subscriptions. Delete one first. |

## Test the delivery

[`POST /webhooks/{id}/test`](/api-reference/operations/testwebhook/) immediately sends a signed sample event to the subscription's URL and reports how your endpoint answered. The sample uses the first event of the subscription and carries `"is_test": true`.

**cURL**

```bash
curl -X POST https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test \
  -H "Authorization: Bearer $WHATSETTER_API_KEY"
```

**JavaScript**

```js
const res = await fetch('https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.WHATSETTER_API_KEY}` },
});
console.log(await res.json());
```

**Python**

```python
import os, requests

r = requests.post(
    "https://app.whatsetter.com/api/v1/webhooks/66f1c0ffee00000000000abc/test",
    headers={"Authorization": f"Bearer {os.environ['WHATSETTER_API_KEY']}"},
)
print(r.json())
```

```json
{
  "data": {
    "delivered": true,
    "endpoint_status": 200,
    "error": null,
    "event_id": "evt_9f2c1a7e4b8d3056a1cf7e2b9d4a6013"
  }
}
```

`delivered` is `false` when your endpoint answered a non-2xx status (see `endpoint_status`) or could not be reached within 10 seconds (see `error`). A `404 not_found` means the subscription id is unknown or belongs to another workspace.

## What you receive

Every delivery shares the same top-level envelope. The event's own fields sit **next to** the envelope fields, not nested under a `payload` key.

```json
{
  "event_type": "contact.qualified",
  "event_id": "evt_9f2c1a7e4b8d3056a1cf7e2b9d4a6013",
  "api_version": "2026-06-01",
  "occurred_at": "2026-09-15T09:10:12.517Z",
  "team_id": "6b0c1d2e3f405162738a",
  "is_test": false,

  "campaign": {
    "id": "6b0c1d2e3f4051627abc",
    "slug": "acme-morocco-1-ab12",
    "name": "Alex"
  },
  "contact": {
    "id": "6b0c1d2e3f4051627def",
    "lead_id": "212600000000@c.us",
    "name": "Sam",
    "phone": "212600000000",
    "classification": "qualified",
    "ai_reasoning": "Looking for an SUV, budget confirmed, wants a callback.",
    "conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=212600000000%40c.us",
    "external_reference": "your-crm-id-12345"
  }
}
```

### Envelope fields

| Field | Notes |
|---|---|
| `event_type` | One of the events above. |
| `event_id` | Unique per delivery. Use it to deduplicate. |
| `api_version` | Currently `2026-06-01`. |
| `occurred_at` | ISO 8601, UTC. |
| `team_id` | The WhatSetter workspace the event belongs to. |
| `is_test` | `true` when sent from `POST /webhooks/{id}/test`. |

### `contact.qualified` and `contact.not_qualified`

| Field | Notes |
|---|---|
| `campaign.id` | Internal campaign id. |
| `campaign.slug` | Stable, human-readable campaign identifier. |
| `campaign.name` | The agent's display name. |
| `contact.id` | Internal lead id, the same `id` as in `GET /leads`. |
| `contact.lead_id` | Raw WhatsApp id, for example `212600000000@c.us`. |
| `contact.name` | Name detected by the agent, may be `null`. |
| `contact.phone` | Digits only, see the caution below. |
| `contact.classification` | The agent's verdict. |
| `contact.ai_reasoning` | Why the agent decided that, in plain text. |
| `contact.conversation_url` | Deep link into the WhatSetter inbox. |
| `contact.external_reference` | Your own id, see the tip below. |

> **`phone` has no `+`**
`contact.phone` is the international number **without a leading `+`**: `212600000000`, not `+212600000000`. Match on digits only, or prepend the `+` yourself. `contact.lead_id` carries the raw WhatsApp id if you prefer that.

> **`external_reference` tells you whose lead it is**
When you create a lead through [`POST /campaigns/{id}/leads`](/api-reference/operations/addcampaignlead/), pass your own identifier as `external_reference`. We store it and return it on every event for that contact.

It is `null` for any lead we did not receive from you: a CSV imported in the dashboard, or someone who messaged the agent first. **A `null` means the lead does not exist on your side: skip it, it is not a failed match.**

### `agent.disconnected`

```json
{
  "event_type": "agent.disconnected",
  "event_id": "evt_…",
  "api_version": "2026-06-01",
  "occurred_at": "2026-09-14T13:00:09.250Z",
  "team_id": "6b0c1d2e3f405162738a",
  "is_test": false,

  "agent": {
    "name": "Alex",
    "phone": "212611111111@c.us",
    "campaign_id": "acme-morocco-1-ab12",
    "campaign_name": "Acme Morocco 1",
    "session_status": "disconnected",
    "disconnected_at": "2026-09-14T12:54:00.000Z"
  }
}
```

Sent once, when the incident is first detected. Reconnection reminders do not re-send it.

### `booking.created`

Sent when your agent books a meeting in the conversation (**Book in the conversation** on). A meeting the lead books on their own through a link is not reported. `campaign` and `contact` are the same blocks as in `contact.qualified`.

```json
{
  "event_type": "booking.created",
  "event_id": "evt_…",
  "api_version": "2026-06-01",
  "occurred_at": "2026-10-18T14:02:41.118Z",
  "team_id": "6b0c1d2e3f405162738a",
  "is_test": false,

  "campaign": { "id": "6b0c1d2e3f4051627abc", "slug": "acme-berlin-1-cd34", "name": "Julia" },
  "contact": {
    "id": "6b0c1d2e3f4051627def",
    "lead_id": "491701234567@c.us",
    "name": "Max",
    "phone": "491701234567",
    "conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=491701234567%40c.us",
    "external_reference": "your-crm-id-12345"
  },
  "booking": {
    "id": "6b0c1d2e3f4051627fed",
    "start": "2026-10-20T08:00:00.000Z",
    "end": "2026-10-20T08:30:00.000Z",
    "timezone": "Europe/Berlin",
    "status": "confirmed",
    "provider": "cal_com",
    "attendee_email": "max@example.com",
    "attendee_phone": "+491701234567",
    "meeting_url": "https://app.cal.com/video/abc123",
    "location": null
  }
}
```

| Field | Notes |
|---|---|
| `booking.id` | The meeting in WhatSetter. |
| `booking.start`, `booking.end` | ISO 8601, UTC. |
| `booking.timezone` | The time zone the times were offered in. |
| `booking.status` | `confirmed`, or `pending` when your event type needs you to accept the meeting. |
| `booking.provider` | `cal_com`, `calendly` or `ghl`. |
| `booking.attendee_email`, `booking.attendee_phone` | What the meeting was booked with, may be `null`. The phone here has its `+`. |
| `booking.meeting_url` | The video link, when your calendar tool gives one. |
| `booking.location` | The place, for a meeting in person or by phone. |

It arrives after your agent's reply to the lead, usually within a minute.

### `message.received`

Sent for each message a lead writes to one of your agents in a private chat (not in groups), once your agent has read it. It is sent too when someone of your team has taken over the conversation. It is not sent for a number you blocked.

```json
{
  "event_type": "message.received",
  "event_id": "evt_…",
  "api_version": "2026-06-01",
  "occurred_at": "2026-10-18T14:01:07.540Z",
  "team_id": "6b0c1d2e3f405162738a",
  "is_test": false,

  "campaign": { "id": "6b0c1d2e3f4051627abc", "slug": "acme-berlin-1-cd34", "name": "Julia" },
  "contact": {
    "id": "6b0c1d2e3f4051627def",
    "lead_id": "491701234567@c.us",
    "name": "Max",
    "phone": "491701234567",
    "conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=491701234567%40c.us",
    "external_reference": null
  },
  "message": {
    "id": "false_491701234567@c.us_3EB0A1B2C3D4E5F6",
    "text": "Hallo, ich hätte eine Frage zu Dubai.",
    "has_media": false,
    "received_at": "2026-10-18T14:00:55.000Z"
  }
}
```

| Field | Notes |
|---|---|
| `message.id` | The WhatsApp id of the message. |
| `message.text` | What the lead wrote, up to 4,096 characters. `null` for a photo or a voice note without text. |
| `message.has_media` | `true` when the message holds a photo, a document or a voice note. |
| `message.received_at` | When WhatsApp received it, ISO 8601, UTC. |

`contact.phone` is `null` when WhatsApp hides the lead's number. `contact.id` can be `null` on a lead's very first message. It arrives after your agent's reply, usually within a minute.

## Webhooks set on an agent

Besides your subscriptions, each agent can call up to 3 webhook URLs of its
own. They are set in the dashboard, not through the API: the agent's
**Settings**, **Hand-off & alerts**, **Via webhook (advanced)**, with an
optional **Signing secret**. See
[Notifications & alerts](/dashboard/notifications/).

Those URLs receive the qualified or not qualified leads the agent is set to
report, and `contact.label_added`. `contact.label_added` only exists there:
`POST /webhooks` does not accept it.

### `contact.label_added`

Sent when the agent puts one of its labels on a lead, for the labels chosen
under **And when the agent puts the label** in **Hand-off & alerts**. See
[Agent labels](/dashboard/labels/).

```json
{
  "event_type": "contact.label_added",
  "event_id": "evt_4b1f0c9a2d7e4f3a8b6c5d0e1f2a3b4c",
  "api_version": "2026-06-01",
  "occurred_at": "2026-10-19T09:14:03.201Z",
  "team_id": "6b0c1d2e3f405162738a",

  "campaign": { "id": "6b0c1d2e3f4051627abc", "slug": "acme-berlin-1-cd34", "name": "Julia" },
  "contact": {
    "id": "6b0c1d2e3f4051627def",
    "lead_id": "491701234567@c.us",
    "name": "Max",
    "phone": "+491701234567",
    "conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=491701234567%40c.us"
  },
  "label": {
    "id": "t3k9x2ab",
    "label": "Budget confirmed",
    "posed_by": "ai",
    "reason": "The lead gives a budget of 5,000 euros, which fits the offer."
  },
  "is_test": false
}
```

| Field | Notes |
|---|---|
| `campaign.id`, `campaign.slug`, `campaign.name` | The agent, as in `contact.qualified`. |
| `contact.id` | Internal lead id, the same `id` as in `GET /leads`. |
| `contact.lead_id` | Raw WhatsApp id. |
| `contact.name` | Name of the lead, an empty string when unknown. |
| `contact.phone` | With its leading `+` here, unlike `contact.qualified`. |
| `contact.conversation_url` | Deep link into the WhatSetter inbox. |
| `label.id` | The label's id in the agent's settings. It stays the same when the label is renamed. |
| `label.label` | The label's name. |
| `label.posed_by` | `ai` when the AI read it in the conversation, or the fact that put it: `fact:first_message`, `fact:booked` or `fact:no_reply`. |
| `label.reason` | Why: the AI's own sentence, or the fact in a sentence, in the agent's notification language. Can be empty. |

This event has no `classification` and no `external_reference`. It is sent:

- only for a lead active in the last 24 hours. When the labels are switched on, the agent reads older conversations once without sending anything;
- once each time the agent puts the label, never for a label put by a person;
- never while the agent's labels are off.

The headers are the ones below, with `X-Whatsetter-Event: contact.label_added`.
`X-Whatsetter-Signature` is there only when the agent has a **Signing secret**,
and it is computed with that secret, not with a subscription's `whsec_…`.
Each call is tried once, waits 6 seconds at most, does not follow redirects,
and only goes to a public `https://` address.

## Verify the signature

Every delivery is signed with **HMAC-SHA256 of the raw request body**, using your subscription secret. The headers you receive:

```
Content-Type: application/json
User-Agent: Whatsetter-Webhooks/1.0
X-Whatsetter-Event: contact.qualified
X-Whatsetter-Delivery: evt_9f2c1a7e4b8d3056a1cf7e2b9d4a6013
X-Whatsetter-Timestamp: 2026-09-15T09:10:12.517Z
X-Whatsetter-Api-Version: 2026-06-01
X-Whatsetter-Signature: sha256=<hex>
```

`X-Whatsetter-Delivery` repeats the envelope's `event_id`, and `X-Whatsetter-Timestamp` its `occurred_at`. Compute `sha256=` + the hex HMAC of the raw body, then compare it to `X-Whatsetter-Signature` in constant time.

**Node.js**

```js
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody) // the RAW body, before any JSON.parse
    .digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: keep the raw body for this route
// app.post('/webhooks/whatsetter', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verify(req.body, req.get('X-Whatsetter-Signature'), process.env.WHATSETTER_WEBHOOK_SECRET)) {
//     return res.status(401).end();
//   }
//   const event = JSON.parse(req.body);
//   res.status(200).end(); // answer fast, process asynchronously
// });
```

**Python**

```python
import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

# Flask: use request.get_data(), not request.json, so the body stays raw
# @app.post("/webhooks/whatsetter")
# def whatsetter_webhook():
#     if not verify(request.get_data(), request.headers.get("X-Whatsetter-Signature", ""), os.environ["WHATSETTER_WEBHOOK_SECRET"]):
#         return "", 401
#     event = request.get_json()
#     return "", 200
```

**PHP**

```php
<?php
function verify(string $rawBody, string $header, string $secret): bool
{
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $header);
}

$rawBody = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_WHATSETTER_SIGNATURE'] ?? '';

if (!verify($rawBody, $header, getenv('WHATSETTER_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
$event = json_decode($rawBody, true);
http_response_code(200);
```

> **Verify against the raw body**
If your framework parses JSON before you (Express `json()`, Flask `request.json`), re-serializing can change key order or spacing and break the signature. Always hash the bytes exactly as received.

## Delivery rules

- **One attempt per event.** If your endpoint is down or answers an error, the event is **not retried** and is lost. Keep the endpoint available, and reconcile with `GET /leads` if you suspect a gap.
- The request times out after **10 seconds**. Answer `2xx` right away and do your processing asynchronously; a timeout counts as a failure.
- Deduplicate on `event_id` anyway. It costs nothing and protects you if retries are introduced later.
- An event fans out to every active subscription that includes it, up to **10 subscriptions per workspace**. Two subscriptions to the same URL each get their own copy.
- `last_delivery_at` and `last_delivery_status` on the subscription tell you how the last delivery went.

## Manage subscriptions

- [GET /webhooks](/api-reference/operations/listwebhooks/) lists your subscriptions, without the secret.
- [`DELETE /webhooks/{id}`](/api-reference/operations/deletewebhook/) stops deliveries immediately. To change the URL or the events, delete and create again: you get a new secret.

## Related

- [Quickstart](/developers/quickstart/)
- [Errors, limits and idempotency](/developers/errors/)
- [Leads guide](/developers/guides/leads/)
- [Campaigns guide](/developers/guides/campaigns/)
