# Webhooks signés

> Reçois les événements WhatSetter sur ton serveur dès qu'ils se produisent, vérifie la signature HMAC-SHA256 en Node.js, Python ou PHP, et teste ton endpoint.

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

Plutôt que d'interroger l'API en boucle, laisse WhatSetter **pousser** les événements vers ton serveur dès qu'ils se produisent. Chaque livraison est signée, tu es donc sûr qu'elle vient de nous.

## Les événements

| Événement | Déclenché quand | État |
|---|---|---|
| `contact.qualified` | L'agent qualifie un lead (selon les critères de ton prompt) | En service |
| `contact.not_qualified` | L'agent écarte un lead | En service |
| `agent.disconnected` | Un numéro WhatsApp se déconnecte | En service |
| `booking.created` | Ton agent réserve un rendez-vous dans la conversation | En service |
| `message.received` | Un lead écrit à l'un de tes agents | En service |

> **`message.received` arrive souvent**
Il part pour chaque message qu'un lead écrit à tes agents. Abonne-toi seulement si ton serveur a besoin de chaque message.

> **Une étiquette posée par l'agent : `contact.label_added`**
Il ne vient pas d'une souscription. Il part vers les URL de webhook réglées dans **Transfert et alertes** d'un agent, pour les étiquettes choisies là. Vois [Les webhooks réglés sur un agent](#les-webhooks-réglés-sur-un-agent).

## Créer une souscription

[POST /webhooks](/api-reference/operations/createwebhook/) demande le scope `webhooks:manage`. L'URL doit être une adresse HTTPS publique : `localhost`, les réseaux privés et les adresses réservées sont refusés.

**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://ton-serveur.com/webhooks/whatsetter","events":["contact.qualified","contact.not_qualified"],"description":"Sync CRM"}'
```

**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://ton-serveur.com/webhooks/whatsetter',
    events: ['contact.qualified', 'contact.not_qualified'],
    description: 'Sync CRM',
  }),
});
const { data } = await res.json();
console.log(data.secret); // whsec_… affiché une seule fois, stocke-le maintenant
```

**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://ton-serveur.com/webhooks/whatsetter",
        "events": ["contact.qualified", "contact.not_qualified"],
        "description": "Sync CRM",
    },
)
print(r.json()["data"]["secret"])  # whsec_… affiché une seule fois, stocke-le maintenant
```

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

La réponse contient le **secret de signature** (`whsec_…`). Il n'est affiché qu'ici : stocke-le immédiatement. Les appels suivants à [GET /webhooks](/api-reference/operations/listwebhooks/) ne renvoient que `secret_prefix`.

Les erreurs qui comptent :

| HTTP | `code` | Pourquoi |
|---|---|---|
| 422 | `validation_error` | `url` manquante ou pas en HTTPS, `events` vide ou inconnu, `description` de plus de 255 caractères. |
| 429 | `quota_exceeded` | L'espace a déjà 10 souscriptions. Supprimes-en une d'abord. |

## Tester la livraison

[`POST /webhooks/{id}/test`](/api-reference/operations/testwebhook/) envoie immédiatement un événement d'exemple signé vers l'URL de la souscription et te dit comment ton endpoint a répondu. L'exemple utilise le premier événement de la souscription et porte `"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` vaut `false` quand ton endpoint a répondu autre chose qu'un statut 2xx (voir `endpoint_status`) ou n'a pas pu être joint en 10 secondes (voir `error`). Un `404 not_found` signifie que l'identifiant de souscription est inconnu ou appartient à un autre espace.

## Ce que tu reçois

Chaque livraison partage la même enveloppe. Les champs propres à l'événement se trouvent **à côté** de ceux de l'enveloppe, et non imbriqués sous une clé `payload`.

```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": "Cherche un SUV, budget confirmé, veut être rappelé.",
    "conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=212600000000%40c.us",
    "external_reference": "your-crm-id-12345"
  }
}
```

### Champs de l'enveloppe

| Champ | Détail |
|---|---|
| `event_type` | L'un des événements ci-dessus. |
| `event_id` | Unique par livraison. Sert à dédupliquer. |
| `api_version` | Actuellement `2026-06-01`. |
| `occurred_at` | ISO 8601, en UTC. |
| `team_id` | L'espace WhatSetter concerné. |
| `is_test` | `true` si envoyé depuis `POST /webhooks/{id}/test`. |

### `contact.qualified` et `contact.not_qualified`

| Champ | Détail |
|---|---|
| `campaign.id` | Identifiant interne de la campagne. |
| `campaign.slug` | Identifiant stable et lisible de la campagne. |
| `campaign.name` | Le nom affiché de l'agent. |
| `contact.id` | Identifiant interne du lead, le même `id` que dans `GET /leads`. |
| `contact.lead_id` | Identifiant WhatsApp brut, par exemple `212600000000@c.us`. |
| `contact.name` | Prénom détecté par l'agent, parfois `null`. |
| `contact.phone` | Chiffres seuls, voir l'avertissement ci-dessous. |
| `contact.classification` | Le verdict de l'agent. |
| `contact.ai_reasoning` | Pourquoi l'agent a tranché ainsi, en clair. |
| `contact.conversation_url` | Lien direct vers la conversation dans WhatSetter. |
| `contact.external_reference` | Ton propre identifiant, voir l'astuce ci-dessous. |

> **`phone` n'a pas de `+`**
`contact.phone` est le numéro international **sans le `+`** : `212600000000`, pas `+212600000000`. Compare sur les chiffres seuls, ou ajoute le `+` toi-même. `contact.lead_id` te donne l'identifiant WhatsApp brut si tu préfères celui-là.

> **`external_reference` dit à qui appartient le lead**
Quand tu crées un lead via [`POST /campaigns/{id}/leads`](/api-reference/operations/addcampaignlead/), passe ton propre identifiant dans `external_reference`. On le stocke et on te le renvoie dans chaque événement concernant ce contact.

Il vaut `null` pour tout lead qui ne vient pas de toi : un CSV importé depuis le dashboard, ou quelqu'un qui a écrit à l'agent de lui-même. **Un `null` signifie que le lead n'existe pas chez toi : ignore-le, ce n'est pas un rattachement raté.**

### `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"
  }
}
```

Envoyé une seule fois, à la détection de l'incident. Les rappels de reconnexion ne le renvoient pas.

### `booking.created`

Envoyé quand ton agent réserve un rendez-vous dans la conversation (**Réserver dans la conversation** activé). Un rendez-vous que le lead prend seul par un lien n'est pas signalé. `campaign` et `contact` sont les mêmes blocs que dans `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
  }
}
```

| Champ | Notes |
|---|---|
| `booking.id` | Le rendez-vous dans WhatSetter. |
| `booking.start`, `booking.end` | ISO 8601, UTC. |
| `booking.timezone` | Le fuseau horaire dans lequel les horaires ont été proposés. |
| `booking.status` | `confirmed`, ou `pending` quand ton type d'événement te demande d'accepter le rendez-vous. |
| `booking.provider` | `cal_com`, `calendly` ou `ghl`. |
| `booking.attendee_email`, `booking.attendee_phone` | Ce avec quoi le rendez-vous a été pris, peut être `null`. Ici, le téléphone a son `+`. |
| `booking.meeting_url` | Le lien de visio, quand ton outil de calendrier en donne un. |
| `booking.location` | Le lieu, pour un rendez-vous sur place ou par téléphone. |

Il arrive après la réponse de ton agent au lead, en général en moins d'une minute.

### `message.received`

Envoyé pour chaque message qu'un lead écrit à l'un de tes agents en conversation privée (pas dans les groupes), une fois que ton agent l'a lu. Il part aussi quand quelqu'un de ton équipe a pris la conversation en main. Il ne part pas pour un numéro que tu as bloqué.

```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"
  }
}
```

| Champ | Notes |
|---|---|
| `message.id` | L'identifiant WhatsApp du message. |
| `message.text` | Ce que le lead a écrit, jusqu'à 4 096 caractères. `null` pour une photo ou un vocal sans texte. |
| `message.has_media` | `true` quand le message contient une photo, un document ou un vocal. |
| `message.received_at` | Quand WhatsApp l'a reçu, ISO 8601, UTC. |

`contact.phone` vaut `null` quand WhatsApp cache le numéro du lead. `contact.id` peut valoir `null` au tout premier message d'un lead. Il arrive après la réponse de ton agent, en général en moins d'une minute.

## Les webhooks réglés sur un agent

En plus de tes souscriptions, chaque agent peut appeler jusqu'à 3 URL de
webhook qui lui sont propres. Elles se règlent dans le dashboard, pas par
l'API : **Réglages** de l'agent, **Transfert et alertes**,
**Par webhook (avancé)**, avec un **Secret de signature** facultatif. Vois
[Notifications et alertes](/fr/dashboard/notifications/).

Ces URL reçoivent les leads qualifiés ou non qualifiés que l'agent est réglé
pour signaler, et `contact.label_added`. `contact.label_added` n'existe que
là : `POST /webhooks` ne l'accepte pas.

### `contact.label_added`

Envoyé quand l'agent pose une de ses étiquettes sur un lead, pour les
étiquettes choisies sous **Et quand l'agent pose l'étiquette** dans
**Transfert et alertes**. Vois [Étiquettes de l'agent](/fr/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-paris-1-cd34", "name": "Julia" },
  "contact": {
    "id": "6b0c1d2e3f4051627def",
    "lead_id": "33612345678@c.us",
    "name": "Julien",
    "phone": "+33612345678",
    "conversation_url": "https://app.whatsetter.com/dashboard/conversations?leadId=33612345678%40c.us"
  },
  "label": {
    "id": "t3k9x2ab",
    "label": "Budget validé",
    "posed_by": "ai",
    "reason": "Le lead donne un budget de 5 000 euros, qui correspond à l'offre."
  },
  "is_test": false
}
```

| Champ | Notes |
|---|---|
| `campaign.id`, `campaign.slug`, `campaign.name` | L'agent, comme dans `contact.qualified`. |
| `contact.id` | Id interne du lead, le même `id` que dans `GET /leads`. |
| `contact.lead_id` | Id WhatsApp brut. |
| `contact.name` | Nom du lead, une chaîne vide s'il est inconnu. |
| `contact.phone` | Avec son `+` ici, contrairement à `contact.qualified`. |
| `contact.conversation_url` | Lien direct vers la conversation dans WhatSetter. |
| `label.id` | L'id de l'étiquette dans les réglages de l'agent. Il ne change pas quand l'étiquette est renommée. |
| `label.label` | Le nom de l'étiquette. |
| `label.posed_by` | `ai` quand l'IA l'a lue dans la conversation, ou le fait qui l'a posée : `fact:first_message`, `fact:booked` ou `fact:no_reply`. |
| `label.reason` | Pourquoi : la phrase de l'IA, ou le fait dit en une phrase, dans la langue des notifications de l'agent. Peut être vide. |

Cet événement n'a ni `classification` ni `external_reference`. Il part :

- seulement pour un lead actif dans les dernières 24 heures. Quand les étiquettes sont allumées, l'agent relit une fois les conversations plus anciennes sans rien envoyer ;
- une fois chaque fois que l'agent pose l'étiquette, jamais pour une étiquette posée par une personne ;
- jamais tant que les étiquettes de l'agent sont éteintes.

Les en-têtes sont ceux ci-dessous, avec `X-Whatsetter-Event: contact.label_added`.
`X-Whatsetter-Signature` n'est là que si l'agent a un **Secret de signature**,
et il est calculé avec ce secret, pas avec le `whsec_…` d'une souscription.
Chaque appel est tenté une seule fois, attend 6 secondes au plus, ne suit pas
les redirections, et ne part que vers une adresse `https://` publique.

## Vérifier la signature

Chaque livraison est signée en **HMAC-SHA256 du corps brut de la requête**, avec le secret de ta souscription. Les en-têtes que tu reçois :

```
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` reprend l'`event_id` de l'enveloppe, et `X-Whatsetter-Timestamp` son `occurred_at`. Calcule `sha256=` + le HMAC hexadécimal du corps brut, puis compare-le à `X-Whatsetter-Signature` en temps constant.

**Node.js**

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

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody) // le corps BRUT, avant tout JSON.parse
    .digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express : garde le corps brut pour cette 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(); // réponds vite, traite en asynchrone
// });
```

**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 : utilise request.get_data(), pas request.json, pour garder le corps brut
# @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);
```

> **Vérifie sur le corps brut**
Si ton framework parse le JSON avant toi (Express `json()`, Flask `request.json`), la re-sérialisation peut changer l'ordre des clés ou les espaces et casser la signature. Hache toujours les octets exactement tels que reçus.

## Les règles de livraison

- **Un seul essai par événement.** Si ton endpoint est indisponible ou répond une erreur, l'événement **n'est pas réessayé** et il est perdu. Garde ton endpoint disponible, et réconcilie avec `GET /leads` si tu soupçonnes un trou.
- La requête expire après **10 secondes**. Réponds `2xx` tout de suite et fais ton traitement en asynchrone ; un timeout compte comme un échec.
- Déduplique quand même sur l'`event_id`. Ça ne coûte rien et ça te protège si des nouvelles tentatives arrivent plus tard.
- Un événement est diffusé à chaque souscription active qui le contient, jusqu'à **10 souscriptions par espace**. Deux souscriptions vers la même URL reçoivent chacune leur copie.
- `last_delivery_at` et `last_delivery_status` sur la souscription te disent comment s'est passée la dernière livraison.

## Gérer les souscriptions

- [GET /webhooks](/api-reference/operations/listwebhooks/) liste tes souscriptions, sans le secret.
- [`DELETE /webhooks/{id}`](/api-reference/operations/deletewebhook/) arrête les livraisons immédiatement. Pour changer l'URL ou les événements, supprime et recrée : tu obtiens un nouveau secret.

## Voir aussi

- [Démarrage rapide](/fr/developers/quickstart/)
- [Erreurs, limites et idempotence](/fr/developers/errors/)
- [Guide Leads](/fr/developers/guides/leads/)
- [Guide Campagnes](/fr/developers/guides/campaigns/)
