Webhooks

Toutes les routes utilisent le header x-api-key. Un abonnement webhook est toujours rattaché à une session (pas au compte entier) — cohérent avec le reste de l’API (statuts récurrents, contacts).

La création et la suppression d’un abonnement webhook se font depuis le dashboard WaaConnect, pas via l’API à clé. Seule la lecture (liste des abonnements actifs) est disponible ici.

Catalogue d’events

Event	Déclenchement
`message.received`	Un message est reçu — envoyé au moment même de la réception, sans être relu depuis une base
`message.sent`	Un message envoyé par cette session a bien été transmis à WhatsApp
`message.status`	Accusé de livraison/lecture d’un message envoyé (`delivered`, `read`, `played`, …)
`message.deleted`	Un message (envoyé ou reçu) est supprimé — par vous ou par votre contact
`message.edited`	Un message (envoyé ou reçu) est édité — par vous ou par votre contact
`message.reaction`	Une réaction emoji est ajoutée (ou retirée) sur un message
`flow.triggered`	Un flow (automatisation) démarre suite à un message reçu
`autoreply.triggered`	Une règle d’auto-réponse par mot-clé se déclenche

Passez events: ["*"] à la création pour tout recevoir, ou une liste explicite pour ne recevoir que certains events.

Format de l’enveloppe

Tous les events partagent la même structure :

{
  "event": "message.received",
  "eventId": "b7e4b8b0-2222-4444-9999-abcdef123456",
  "sessionId": "uuid-session-12",
  "tenantId": "uuid-tenant-1",
  "timestamp": "2026-07-19T10:00:00.000Z",
  "data": { }
}

eventId est unique par event — utilisez-le pour dédupliquer si vous recevez un retry après avoir déjà traité l’event.

`data` selon l’event

// message.received
{
  "chatId": "22997000000@s.whatsapp.net",
  "chatType": "individual",
  "from": "22997000000@s.whatsapp.net",
  "fromPhone": "22997000000@s.whatsapp.net",
  "type": "conversation",
  "content": "Bonjour, vous êtes dispo ?",
  "pushName": "Aicha",
  "messageTimestamp": 1774511000
}

// message.sent
{
  "id": "uuid-message-451",
  "toNumber": "22997000000@s.whatsapp.net",
  "type": "text",
  "content": "Bonjour, votre commande est prête.",
  "waMessageId": "3EB0B430B438B4F26B29",
  "remoteJid": "22997000000@s.whatsapp.net"
}

// message.status
{
  "waMessageId": "3EB0B430B438B4F26B29",
  "remoteJid": "22997000000@s.whatsapp.net",
  "status": "delivered"
}

// message.deleted
{
  "remoteJid": "22997000000@s.whatsapp.net",
  "waMessageId": "3EB0B430B438B4F26B29",
  "fromMe": false,
  "deletedBy": "contact"
}

// message.edited
{
  "remoteJid": "22997000000@s.whatsapp.net",
  "waMessageId": "3EB0B430B438B4F26B29",
  "fromMe": false,
  "editedBy": "contact",
  "newContent": "Bonjour, vous êtes disponible demain ?"
}

// message.reaction
{
  "remoteJid": "22997000000@s.whatsapp.net",
  "waMessageId": "3EB0B430B438B4F26B29",
  "fromMe": true,
  "emoji": "👍"
}

// flow.triggered
{
  "flowId": "uuid-flow-1",
  "flowName": "Accueil nouveau client",
  "chatId": "22997000000@s.whatsapp.net"
}

// autoreply.triggered
{
  "ruleId": "uuid-rule-1",
  "keyword": "tarif",
  "chatId": "22997000000@s.whatsapp.net"
}

`chatType`, `fromPhone` et identifiants `@lid`

WhatsApp adresse aujourd’hui beaucoup de contacts via un identifiant opaque @lid (ex: 39741751881852@lid) plutôt que le JID classique basé sur le numéro de téléphone (@s.whatsapp.net) — une évolution du protocole liée à la confidentialité du numéro, pas une anomalie.

chatType (individual / group / status / broadcast) permet d’identifier directement le type de conversation sans avoir à parser chatId vous-même.
fromPhone est une tentative de résolution du numéro réel derrière un @lid. Peut être null si la correspondance n’est pas encore connue (typiquement pour un tout nouveau contact) — pas de garantie de résolution immédiate ni systématique.

Pour répondre à un message reçu, utilisez chatId comme destinataire (to de Envoyer un message texte). Dans un groupe, from désigne le membre qui a écrit, pas le groupe lui-même — n’utilisez jamais from comme destinataire dans ce cas.

Envoyer directement à un @lid fonctionne — pas besoin d’attendre ou d’avoir la résolution fromPhone pour répondre :

L’URL/numéro passé en to est utilisé tel quel dès qu’il contient déjà un @ (donc un chatId en @lid n’est jamais reformaté à tort comme un numéro).
WhatsApp/Baileys gère nativement le chiffrement vers un destinataire @lid.
Nuance : l’étape interne de vérification “ce numéro existe-t-il sur WhatsApp ?” n’est pas supportée par WhatsApp pour un @lid — elle est silencieusement ignorée pour ce cas précis (pas d’erreur), et l’envoi part quand même normalement vers le chatId d’origine.

fromPhone, quand il est renseigné (non null), fonctionne aussi comme destinataire — c’est un JID classique, sans particularité.

Sécurité — vérifier la signature

Chaque requête envoyée à votre URL inclut deux headers :

X-Waaconnect-Event : le type d’event (ex: message.received)
X-Waaconnect-Signature : sha256=<hmac> — HMAC-SHA256 du corps JSON brut, signé avec le secret renvoyé à la création de l’abonnement.

const crypto = require("crypto");

function isValid(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Le secret n’est affiché qu’une seule fois, au moment de la création de l’abonnement depuis le dashboard. Conservez-le : il n’est jamais réaffiché ensuite, y compris via Lister les webhooks.

Fiabilité

Livraison via une file dédiée avec retry : 5 tentatives, backoff exponentiel (5s / 25s / 125s / …), timeout 8s par tentative.
Après épuisement des tentatives, l’event n’est plus retenté — votre endpoint doit répondre 2xx rapidement pour être considéré comme reçu.

Routes

Lister les abonnements

Vue d'ensemble

Compte

Sessions

Messages

Campagnes & envois groupés

Contacts & Groupes

Groupes

Statuts

Chaines

Endpoints Rapides

Webhooks

Catalogue d’events

Format de l’enveloppe

`data` selon l’event

`chatType`, `fromPhone` et identifiants `@lid`

Sécurité — vérifier la signature

Fiabilité

Routes

​Catalogue d’events

​Format de l’enveloppe

​data selon l’event

​chatType, fromPhone et identifiants @lid

​Sécurité — vérifier la signature

​Fiabilité

​Routes

Catalogue d’events

Format de l’enveloppe

`data` selon l’event

`chatType`, `fromPhone` et identifiants `@lid`

Sécurité — vérifier la signature

Fiabilité

Routes