InloggenGratis proefperiode starten
Meta Tech Provider

WhatsApp-webhook: herhalingen, dubbele berichten en volgorde: zo verwerk je ze

Meta herhaalt een WhatsApp-webhook die iets anders dan HTTP 200 krijgt, eerst direct en daarna steeds minder vaak, tot 7 dagen. Daarna laat Meta hem vallen. Herhalingen gaan naar elke app die op het account is geabonneerd, dus dubbele berichten zijn normaal. Antwoord snel met 200 en dedupliceer op het bericht-id, of op status-id plus de status, en sorteer gebeurtenissen op hun eigen tijdstempels.

easyCoexistence koppelt je WhatsApp Business-app-nummer via Coexistence aan Meta's Cloud API en vangt Meta's herhalingen op voordat je automatiseringen ze zien, zodat een opnieuw afgeleverd bericht geen tweede AI-antwoord krijgt.

7 days

Hoe lang Meta een webhook blijft herhalen die geen HTTP 200 kreeg, voordat het die laat vallen.

1,000

De meeste updates bundelt Meta in één POST; Meta belooft geen bundeling, dus verwerk elk verzoek apart.

3 MB

Grootste payload die een WhatsApp-webhook-POST kan bevatten.

7 days

Hoe lang easyCoexistence elk binnenkomend bericht-id onthoudt, zodat een opnieuw afgeleverd bericht geen automatisering twee keer uitvoert.

7 attempts

Pogingen per doorstuur naar je Forward URL, elk wachtend 10 seconden op een 2xx, over ongeveer 33 uur.

Wanneer herhaalt Meta een WhatsApp-webhook?

Telkens wanneer een aflevering aan je endpoint een andere HTTP-status dan 200 krijgt, of helemaal niet kan worden afgeleverd. Meta probeert direct opnieuw en daarna nog een paar keer, steeds minder vaak, gedurende de volgende 7 dagen. Wat dan nog niet is bevestigd, laat Meta daarna vallen. De herhalingen gaan naar elke app die voor dat veld op het WhatsApp Business Account is geabonneerd, en daarom waarschuwt Meta dat ze dubbele meldingen kunnen opleveren. Er is geen API om eerdere webhooks op te halen, dus een aflevering die na 7 dagen nog niet is gelukt, is voor je systeem verloren.

Waarom komen dubbele berichten ook als je server gezond is?

Omdat een aflevering aan jouw kant kan slagen en toch als mislukt lijkt voor Meta. Een handler die zijn werk doet voordat hij antwoordt, kan langer duren dan Meta's wachttijd, waardoor Meta iets opnieuw verstuurt wat je al hebt verwerkt. Een uitrol die de server midden in een verzoek herstart, een loadbalancer die even 502 teruggeeft, of een 201 of 204 in plaats van 200 tellen allemaal als mislukking. Bundels voegen nog een geval toe: één POST kan veel updates bevatten, dus een time-out op een grote bundel stuurt de hele bundel terug, inclusief de updates die je al hebt afgehandeld.

Op welke sleutel moet je dedupliceren?

Op Meta's eigen id's, per gebeurtenistype gekozen, want één bericht levert legitiem meerdere webhooks op. Een statussleutel zonder de statuswaarde zou delivered en read als kopieën van sent laten vallen, en een oproep-sleutel zonder de gebeurtenis zou alleen de eerste fase van een oproep bewaren. Sla de sleutels op met een unieke index, zodat twee workers die dezelfde herhaling verwerken niet allebei winnen:

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.

In welke volgorde komen webhooks binnen?

Niet noodzakelijk in de volgorde waarin dingen gebeurden. Meta's documentatie belooft geen volgorde, een herhaalde aflevering komt na nieuwere binnen, en een status kan een stap overslaan: Meta stuurt read zonder delivered wanneer een bericht op het moment van aankomst al gelezen is. Sla gebeurtenissen dus op met hun eigen tijdstempelveld, vergelijk een status op rang in plaats van op aankomst, en laat een later klantbericht winnen van een eerder bericht dat te laat binnenkwam. Bij een Coexistence-nummer kan de eenmalige geschiedenisimport rond de onboarding overlappen met live berichten, en het bericht-id is wat de twee met elkaar verzoent.

Hoe ziet een veilige handler eruit?

Vier stappen: verifieer, antwoord precies met 200, dedupliceer, en werk dan vanuit een wachtrij, zodat niets traags tussen Meta's verzoek en je antwoord zit. Deze versie controleert X-Hub-Signature-256 met het secret van je eigen Meta-app. Voor een nummer dat via easyCoexistence is gekoppeld, ondertekent Meta met het app-secret van easyCoexistence, dus een directe bestemming authenticeert zich met een lang secret in het URL-pad, of je schakelt over op beheerde doorsturing, per nummer ondertekend.

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);

Hoe gaat easyCoexistence om met herhalingen op een gekoppeld nummer?

Bij binnenkomst controleert easyCoexistence de handtekening van Meta, antwoordt met 200 en voert automatiseringen uit na het antwoord, zodat Meta niet opnieuw probeert omdat een AI-antwoord een paar seconden duurde. Elk binnenkomend bericht-id wordt 7 dagen bewaard, de lengte van Meta's herhalingsvenster, en een opnieuw afgeleverd bericht wordt herkend en start geen tweede automatisch antwoord.

Bij uitgaand verkeer naar je Forward URL wordt elke Meta-wijziging één aflevering met een id in X-EC-Delivery dat gelijk blijft over alle doorstuurpogingen: 7 pogingen gedurende ongeveer 33 uur, elk wachtend 10 seconden op een 2xx. Een wijziging die Meta zelf opnieuw aflevert, wordt opnieuw doorgestuurd onder een nieuw aflever-id, dus dedupliceer ook binnen value op Meta's id's.

Veelgemaakte fouten

  • Statussen dedupliceren op id alleen. sent, delivered en read delen de wamid, dus de sleutel heeft ook de status nodig.
  • Eerst verwerken, dan pas antwoorden. Een trage handler laat Meta werk opnieuw proberen dat je al hebt gedaan; antwoord eerst met 200 en werk vanuit een wachtrij.
  • 201 of 204 teruggeven. Meta's documentatie ziet elke status anders dan 200 als mislukte aflevering en probeert opnieuw.
  • Doorgestuurde berichten alleen dedupliceren op X-EC-Delivery. Een wijziging die Meta opnieuw aflevert, komt binnen onder een nieuw aflever-id; houd Meta's id's als tweede sleutel.
Dit doen met EasyCoexistence

Doorgestuurde berichten naar je server zijn ondertekend, in de wachtrij gezet en opnieuw geprobeerd, en elk nummer wordt 24/7 bewaakt. US$ 9 tot US$ 0,75 per nummer per maand, dalend naarmate je nummers toevoegt, met een gratis proefperiode van 3 dagen.

Veelgestelde vragen

Hoe lang moet ik de id's bewaren die ik al heb gezien?

Minstens 7 dagen, Meta's herhalingsvenster. Een aflevering die Meta op dag zes opnieuw probeert, moet nog steeds bij de sleutel passen, anders wordt ze als nieuw verwerkt.

Wat gebeurt er met de berichten van mijn klanten als mijn endpoint dagenlang niet bereikbaar is?

Meta probeert tot 7 dagen opnieuw en laat de webhooks daarna vallen. Bij een Coexistence-nummer staan de gesprekken nog gewoon in de WhatsApp Business-app op de telefoon, zodat het bedrijf vanaf daar kan antwoorden.

Kan ik webhooks die ik heb gemist opnieuw afspelen?

Niet via Meta: er is geen API voor historische webhookdata. De eenmalige geschiedenisimport van een Coexistence-nummer loopt alleen bij de onboarding en kan voor dezelfde koppeling niet opnieuw worden aangevraagd.

Stuurt Meta dezelfde update naar meer dan één server?

Het stuurt naar elke app die voor het WhatsApp Business Account op dat veld is geabonneerd. Met een bestemmingsoverride gaan de berichtvelden van het nummer naar de override-URL in plaats van naar de standaard callback van die app.

Lees verder

Klaar om te beginnen?

Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.

Start je gratis proefperiode

Geverifieerd op