Se connecterCommencer l’essai gratuit
Meta Tech Provider

Réessais, doublons et ordre des webhooks WhatsApp : comment les gérer

Meta réessaie un webhook WhatsApp qui reçoit autre chose qu'un HTTP 200, d'abord immédiatement puis à fréquence décroissante pendant 7 jours, et l'abandonne ensuite. Les réessais sont envoyés à chaque application abonnée au compte, donc les doublons sont normaux. Répondez 200 rapidement, dédupliquez sur l'identifiant du message ou sur l'identifiant de statut plus le statut, et ordonnez les événements selon leurs propres horodatages.

easyCoexistence relie votre numéro de l'application WhatsApp Business à la Cloud API de Meta via Coexistence et absorbe les redélivrances de Meta avant que vos automatisations ne les voient, si bien qu'un message réessayé ne reçoit pas une seconde réponse de l'IA.

7 days

Durée pendant laquelle Meta réessaie un webhook qui n'a pas reçu HTTP 200, avant de l'abandonner.

1,000

La plupart des mises à jour sont regroupées par Meta en un seul POST ; Meta ne garantit pas ce regroupement, donc traitez chaque requête séparément.

3 MB

Taille maximale du payload qu'un POST de webhook WhatsApp peut transporter.

7 days

Durée pendant laquelle easyCoexistence mémorise l'identifiant de chaque message entrant, pour qu'un message redélivré ne lance pas une automatisation deux fois.

7 attempts

Tentatives par transfert vers votre URL de transfert, chacune attendant 10 secondes une réponse 2xx, sur environ 33 heures.

Quand Meta réessaie-t-il un webhook WhatsApp ?

Chaque fois qu'une livraison vers votre endpoint reçoit un statut HTTP autre que 200, ou ne peut pas être livrée du tout. Meta réessaie immédiatement, puis quelques fois de plus à fréquence décroissante pendant les 7 jours suivants, et abandonne ce qui reste non acquitté ensuite. Les réessais sont envoyés à chaque application abonnée au compte WhatsApp Business pour ce champ, ce qui explique que Meta prévienne qu'ils peuvent produire des notifications en double. Aucune API ne permet de récupérer les webhooks passés : une livraison qui épuise ses 7 jours est perdue pour votre système.

Pourquoi des doublons arrivent-ils alors que votre serveur fonctionne bien ?

Parce qu'une livraison peut réussir de votre côté et tout de même paraître échouée pour Meta. Un gestionnaire qui effectue son travail avant de répondre peut dépasser le délai d'attente de Meta, qui réessaie alors quelque chose que vous avez déjà traité. Un déploiement qui redémarre le serveur en pleine requête, un répartiteur de charge renvoyant un 502 pendant un instant, ou un 201 ou 204 au lieu d'un 200 comptent tous comme des échecs. Les lots ajoutent un cas de plus : un seul POST peut contenir de nombreuses mises à jour, donc un délai dépassé sur un gros lot renvoie tout le lot, y compris les mises à jour que vous avez déjà traitées.

Sur quelle clé dédupliquer ?

Les identifiants propres à Meta, choisis selon le type d'événement, car un même message produit légitimement plusieurs webhooks. Une clé de statut sans la valeur du statut supprimerait les statuts délivré et lu, pris pour des copies de « envoyé », et une clé d'appel sans l'événement ne garderait que la première étape d'un appel. Stockez les clés avec un index unique, pour que deux traitements qui gèrent le même réessai ne puissent pas gagner tous les deux :

messages[].idIncoming messages: the wamid.
statuses[].id + statusOne message has sent, delivered, read; each is its own event.
message_echoes[].idReplies the owner typed in the WhatsApp Business app.
calls[].id + eventA call's connect, statuses and terminate share the wacid.
user id + value + timestampuser_preferences: a customer can stop and resume more than once.

Dans quel ordre les webhooks arrivent-ils ?

Pas forcément dans l'ordre où les choses se sont produites. La documentation de Meta ne promet aucun ordre, une livraison réessayée arrive après des livraisons plus récentes, et un statut peut sauter une étape : Meta envoie « lu » sans « délivré » lorsqu'un message est lu dès son arrivée. Enregistrez donc les événements avec leur propre champ d'horodatage, comparez un statut par rang plutôt que par heure d'arrivée, et laissez un message client plus récent l'emporter sur un message plus ancien arrivé en retard. Sur un numéro en Coexistence, l'import unique de l'historique peut chevaucher les messages en direct autour de l'intégration, et l'identifiant du message permet de réconcilier les deux.

À quoi ressemble un gestionnaire sûr ?

Quatre étapes : vérifier, répondre exactement 200, dédupliquer, puis travailler depuis une file d'attente, pour que rien de lent ne s'intercale entre la requête de Meta et votre réponse. Cette version vérifie X-Hub-Signature-256 avec le secret de votre propre application Meta ; pour un numéro connecté via easyCoexistence, Meta signe avec le secret de l'application easyCoexistence, donc une destination directe s'authentifie avec un long secret dans le chemin de son URL, ou bascule vers un transfert géré signé par numéro.

meta-webhook.mjs: 200 first, then deduplicate (Node.js, no dependencies)
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production

// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
  const keys = [];
  for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
  for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
  for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
  for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
  return keys;
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
    const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
    if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // exactly 200, before any work
    const body = JSON.parse(raw.toString("utf8"));
    for (const entry of body.entry ?? []) {
      for (const change of entry.changes ?? []) {
        for (const key of keysOf(change.field, change.value ?? {})) {
          if (seen.has(key)) continue; // a retry of something already accepted
          seen.add(key);
          // queue { key, field: change.field, value: change.value } for a worker here
          console.log("new", key);
        }
      }
    }
  });
}).listen(process.env.PORT ?? 3000);

Comment easyCoexistence gère-t-il les réessais sur un numéro connecté ?

À l'entrée, easyCoexistence vérifie la signature de Meta, répond 200 et lance les automatisations après la réponse, afin que Meta ne réessaie pas parce qu'une réponse de l'IA a pris quelques secondes. Chaque identifiant de message entrant est conservé pendant 7 jours, la durée de la fenêtre de réessai de Meta, et un message redélivré est reconnu et ne déclenche pas une seconde réponse automatique.

À la sortie vers votre URL de transfert, chaque modification de Meta devient une livraison avec un identifiant dans X-EC-Delivery qui reste le même lors des réessais de transfert : 7 tentatives sur environ 33 heures, chacune attendant 10 secondes une réponse 2xx. Une modification que Meta redélivre elle-même est transférée à nouveau sous un nouvel identifiant de livraison ; dédupliquez donc aussi sur les identifiants de Meta à l'intérieur de value.

Erreurs courantes

  • Dédupliquer les statuts sur l'identifiant seul. sent, delivered et read partagent le wamid, donc la clé doit aussi contenir le statut.
  • Traiter avant de répondre. Un gestionnaire lent fait réessayer à Meta un travail déjà fait ; renvoyez 200 d'abord et travaillez depuis une file d'attente.
  • Renvoyer 201 ou 204. La documentation de Meta considère tout statut autre que 200 comme une livraison échouée et la réessaie.
  • Dédupliquer les transferts uniquement sur X-EC-Delivery. Une modification que Meta redélivre arrive sous un nouvel identifiant de livraison ; gardez les identifiants de Meta comme seconde clé.
Faire cela avec EasyCoexistence

Les transferts vers votre serveur sont signés, mis en file d'attente et réessayés, et chaque numéro est surveillé 24h/24 et 7j/7. De US$ 9 à US$ 0,75 par numéro et par mois, en baisse à mesure que vous ajoutez des numéros, avec les 3 premiers jours offerts.

Questions fréquemment posées

Combien de temps dois-je garder les identifiants déjà vus ?

Au moins 7 jours, la fenêtre de réessai de Meta. Une livraison que Meta réessaie le sixième jour doit encore correspondre à sa clé, sinon elle sera traitée comme nouvelle.

Que deviennent les messages de mes clients si mon endpoint est indisponible pendant plusieurs jours ?

Meta réessaie pendant 7 jours au maximum, puis abandonne les webhooks. Sur un numéro en Coexistence, les conversations restent dans l'application WhatsApp Business sur le téléphone, donc l'entreprise peut y répondre.

Puis-je rejouer les webhooks que j'ai manqués ?

Pas depuis Meta : aucune API ne donne accès aux données historiques des webhooks. L'import unique de l'historique d'un numéro en Coexistence n'a lieu qu'à l'intégration et ne peut pas être redemandé pour la même connexion.

Meta envoie-t-il la même mise à jour à plusieurs serveurs ?

Il l'envoie à chaque application abonnée au compte WhatsApp Business pour ce champ. Avec une surcharge de destination, les champs de messages du numéro sont envoyés à l'URL de surcharge au lieu du callback par défaut de cette application.

Poursuivre la lecture

Prêt à commencer ?

Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.

Commencer l'essai gratuit

Vérifié le