Webhooks WhatsApp : événements, sécurité et nouvelles tentatives

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

Comment écrire un gestionnaire fiable ?

Faites trois choses dans l'ordre : stocker l'événement brut, accuser réception par un 2xx, puis traiter de façon asynchrone. Le gestionnaire ci-dessous suit le schéma de notre documentation.

import express from "express";

const app = express();

// Capturez le corps brut pour pouvoir le stocker exactement tel que reçu.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // échec du stockage : laisser l'événement être réessayé
    }
    res.sendStatus(200);          // accuser réception rapidement
    queue.publish("status-events", req.body); // faire le vrai travail ailleurs
  },
);

// Worker : traitement idempotent
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // à adapter selon le canal
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // message inconnu : le journaliser et enquêter
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // doublon ou événement périmé

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # échec du stockage : laisser l'événement être réessayé
    queue.publish("status-events", raw)  # traiter de façon asynchrone
    return "", 200               # accuser réception rapidement

Les objets db et queue sont votre propre stockage et votre propre file de tâches. La table rank est ce qui rend le traitement idempotent : un événement en double ou périmé n'est pas une avancée, il est donc ignoré.

Règles pour un gestionnaire fiable

• Répondez en quelques secondes. Ne faites aucun travail lourd avant de répondre.
• Ne renvoyez 2xx qu'après le stockage de l'événement. Si le stockage échoue, renvoyez 5xx.
• Dédoublonnez par identifiant de message. Le même statut peut arriver plusieurs fois.
• Ne renvoyez jamais un message depuis le gestionnaire. Décidez des nouveaux essais dans une tâche distincte, après vérification du statut.
• Conservez le corps brut pour le dépannage et pour rejouer les événements après une correction.

Comment sécuriser un webhook WhatsApp ?

Cela dépend de qui écrit à votre point de terminaison. Meta signe les webhooks qu'il envoie aux applications que vous enregistrez chez lui. La spécification de l'API OmniChannels.ai ne définit aucun en-tête de signature de webhook : n'en attendez donc pas.

Pour le schéma de Meta, la documentation de Meta indique de générer un hash HMAC-SHA256 de la charge utile JSON avec le secret de votre application et de le comparer à la valeur qui suit sha256= dans l'en-tête X-Hub-Signature-256. Le HMAC lui-même est défini par la RFC 2104. Calculez-le sur les octets bruts, pas sur un objet re-sérialisé, et comparez en temps constant.

Pour notre point de terminaison :

• Utilisez uniquement HTTPS, avec un certificat valide.
• Utilisez un chemin long et impossible à deviner, et changez-le s'il fuit.
• Validez la forme du corps et rejetez tout ce qui est inattendu.
• Traitez les événements comme des notifications. Avant une action irréversible, comme un remboursement ou un verrouillage antifraude, confirmez l'état par un appel d'interrogation.

Que se passe-t-il quand la livraison échoue ?

Les nouvelles tentatives dépendent de l'expéditeur. La documentation de Meta indique qu'il réessaie une livraison échouée à fréquence décroissante pendant jusqu'à 7 jours, ce qui peut produire des notifications en double. C'est une raison d'être idempotent même si vous voyez rarement des doublons. Pour les événements de notre plateforme, confirmez le comportement de réessai avec votre ingénieur d'onboarding au lieu de supposer qu'il est identique à celui de Meta.

Dans les deux cas, construisez en prévoyant la perte autant que la duplication : votre point de terminaison peut être indisponible pendant un déploiement, et une règle de pare-feu peut faire disparaître des requêtes en silence.

Comment récupérer les événements manquants ?

Interrogez le lot, ne renvoyez pas le message.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id est l'identifiant renvoyé par l'appel d'envoi, et page commence à zéro. Lancez un rapprochement nocturne qui lit les lots de la veille et comble les trous.

Checklist de dépannage

1. L'URL est-elle configurée sur le bon compte ou sous-compte ?
2. Le point de terminaison est-il joignable en HTTPS avec un certificat valide ?
3. Répond-il 2xx rapidement, ou dépasse-t-il le délai ?
4. Un pare-feu ou une règle WAF bloque-t-il les requêtes ?
5. Journalisez-vous le corps brut avant l'analyse, pour qu'une erreur d'analyse ne puisse pas masquer l'événement ?

Exemple concret : le pipeline de notifications d'un distributeur

« Souq Rafiq » (société fictive), enseigne de distribution aux Émirats arabes unis, envoie des suivis de commande par WhatsApp et veut un statut exact dans son outil de commandes.

1. Les commandes sont envoyées avec sendbulk, et le batchId est stocké sur la commande. Voir envoyer un message WhatsApp par API.
2. Le point de terminaison de webhook écrit chaque événement dans une table, puis renvoie 200.
3. Un worker classe les statuts et met à jour l'état du message de la commande.
4. Les événements FAILED créent une tâche pour le support avec le motif, et un repli SMS est envisagé selon le repli entre canaux.
5. Les messages entrants des clients sont acheminés vers la boîte de réception partagée pour que les agents puissent répondre dans la fenêtre.
6. Une tâche nocturne appelle bulk-insights pour les lots de la veille et corrige tout ce qui a été manqué.

Quelles sont les erreurs courantes ?

• Du travail lourd avant de répondre, qui provoque des délais dépassés et des livraisons répétées.
• Accuser réception avant de stocker, ce qui perd des événements quand le stockage échoue.
• Se fier à l'ordre. Un SENT tardif qui écrase DELIVERED.
• Coder sur la charge utile illustrative au lieu d'événements réels.
• Re-sérialiser le JSON avant de vérifier une signature, ce qui modifie les octets.
• Renvoyer depuis le gestionnaire, ce qui peut créer une boucle.
• Limites : ce guide décrit le comportement que nous documentons. La politique de réessai et les champs de charge utile de votre compte doivent être confirmés lors de l'onboarding.

Comment OmniChannels.ai vous aide

OmniChannels.ai pousse les statuts de livraison et les messages entrants de WhatsApp, SMS, RCS et d'autres canaux vers votre webhook dans un format normalisé unique, avec des webhooks distincts par sous-compte pour les revendeurs. BroadNet est un Meta Business Solution Provider officiel : les exigences de webhook propres à Meta sont donc gérées pour vous, et vous travaillez avec notre API. Lisez la référence des webhooks et la documentation de l'API WhatsApp, ou voyez comment les événements apparaissent dans la boîte de réception partagée.