· 5 min · TextMeFlow Team

Webhook WhatsApp : tentatives et idempotence avec l'Event-Id

Si vous recevez des messages WhatsApp entrants via un webhook textmeflow, votre endpoint verra tôt ou tard le même événement plusieurs fois. Ce n'est pas un bug : c'est ainsi que fonctionne une livraison de webhooks fiable. Si votre endpoint n'en tient pas compte, vous finirez par envoyer deux fois une réponse, facturer deux fois une commande ou enregistrer des tickets de support en double. Cet article présente la politique de nouvelles tentatives et l'en-tête qui règle tout : X-TextMeFlow-Event-Id.

Pourquoi il y a des nouvelles tentatives

Une livraison de webhook est une requête POST envoyée sur l'internet public vers un serveur que vous contrôlez. Entre textmeflow et votre endpoint, il y a le DNS, TLS, votre répartiteur de charge, la pile de middlewares de votre framework et le code de votre application : n'importe lequel peut échouer ou expirer pendant quelques secondes sans que votre intégration soit en cause. Si textmeflow abandonnait après la première tentative, un simple incident de votre côté entraînerait la perte d'un message WhatsApp. Il réessaie donc.

La conséquence pratique : votre endpoint doit partir du principe qu'il peut recevoir plusieurs fois la même livraison de webhook, et ne pas y voir une erreur.

Le calendrier des tentatives

Chaque tentative de livraison est jugée uniquement sur la réponse HTTP :

  • 2xx dans les 10 secondes : livré, pas de nouvelle tentative.
  • 408, 429, 5xx, ou délai dépassé/erreur réseau : nouvelle tentative possible. textmeflow réessaie jusqu'à 5 fois avec un backoff de 1m, 5m, 30m, 2h, 6h, soit jusqu'à 6 tentatives au total (l'envoi initial plus 5 nouvelles tentatives) réparties sur environ 8 à 9 heures.
  • Tout autre code 4xx : considéré comme un échec, pas de nouvelle tentative. Un 401 signifie presque toujours que votre secret HMAC ne correspond plus à celui configuré : corrigez-le de votre côté plutôt que d'attendre qu'une nouvelle tentative règle le problème.

Après la 6e tentative, la livraison est marquée failed et vous pouvez consulter le résultat de chaque tentative dans /admin/webhook. Répondez vite, avec un 2xx, dès que vous avez mis l'événement en file d'attente de façon durable : ne faites pas de traitement lent (appels d'API, écritures lourdes en base) dans le gestionnaire de requête lui-même, car un 2xx tardif qui dépasse la fenêtre de 10 secondes compte quand même comme un dépassement de délai.

L'en-tête qui rend les nouvelles tentatives sûres

Chaque payload de webhook porte deux identifiants différents, et les confondre est l'erreur la plus courante :

  • X-TextMeFlow-Event-Id : un UUID qui identifie le message. Il reste identique à chaque nouvelle tentative de cette même livraison.
  • X-TextMeFlow-Delivery : un UUID qui identifie la tentative de livraison. Il est différent à chaque nouvelle tentative, ce qui est utile pour chercher une tentative précise dans les logs, mais inutile pour dédoublonner.

Pour rendre votre endpoint idempotent, enregistrez X-TextMeFlow-Event-Id comme clé primaire (ou colonne à index unique) partout où vous conservez les messages entrants, et vérifiez-le avant d'agir sur un nouveau message :

$eventId = $request->header('X-TextMeFlow-Event-Id');

if (InboundMessage::where('event_id', $eventId)->exists()) {
    return response('', 200); // déjà traité, on acquitte et on s'arrête
}

InboundMessage::create([
    'event_id' => $eventId,
    'payload'  => $request->getContent(),
]);

// ...mettez le traitement proprement dit en file d'attente, puis renvoyez un 2xx
return response('', 200);

Le même schéma fonctionne dans n'importe quel langage : une contrainte d'unicité sur l'event id et un retour anticipé. Pas de verrou distribué, pas de fenêtre de dédoublonnage à régler : l'identifiant reste stable pendant toute la vie de cette livraison, un simple contrôle d'unicité suffit donc.

Combinez-le avec la vérification de signature

L'idempotence et la vérification de signature résolvent des problèmes différents, et il vous faut les deux. Vérifier X-TextMeFlow-Signature (HMAC-SHA256 sur le corps brut, comparé en temps constant) confirme que la requête provient bien de textmeflow ; contrôler X-TextMeFlow-Event-Id confirme que vous n'avez pas déjà traité ce message précis. Consultez Vérifier les signatures des webhooks WhatsApp pour la partie signature, et la référence complète des en-têtes et des nouvelles tentatives dans la documentation des webhooks.

Ce que cela évite en pratique

  • Un client qui reçoit deux fois la même réponse automatique parce que votre gestionnaire s'est exécuté à la fois sur la tentative initiale et sur une nouvelle tentative déclenchée par une réponse trop lente.
  • Un statut de commande qui bascule d'un état à l'autre quand deux tentatives se font concurrence : dédoublonnez sur l'event id avant de toucher à un état modifiable.
  • Des alertes bruyantes : si votre outil de suivi d'erreurs se déclenche à chaque 5xx récupérable, vous serez réveillé pour les échecs mêmes que le calendrier de nouvelles tentatives est conçu pour absorber seul.

Faites cela correctement une fois, tout en haut de votre gestionnaire de webhooks, et chaque intégration que vous construisez par-dessus (confirmations de commande, création de tickets de support, synchronisation CRM) hérite de cette sécurité sans effort.

Envie de voir le comportement des nouvelles tentatives par vous-même ? Créez un compte textmeflow gratuit, configurez un endpoint de webhook et utilisez le test en un clic dans /admin/webhook pour voir arriver les en-têtes.

Envie d'envoyer des messages WhatsApp via API ?

Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.

Gratuit pour toujours