Retry, duplicati e ordine dei webhook WhatsApp: come gestirli
Meta ritenta un webhook WhatsApp che non riceve HTTP 200, subito e poi con frequenza decrescente per un massimo di 7 giorni, quindi lo scarta. I ritentativi vanno a ogni app iscritta al WhatsApp Business Account, quindi i duplicati sono normali. Rispondi 200 in fretta, deduplica sull'id del messaggio o sull'id dello stato più il valore dello stato, e ordina gli eventi con i loro timestamp.
easyCoexistence collega il numero della tua app WhatsApp Business alla Cloud API di Meta tramite Coexistence e assorbe le riconsegne di Meta prima che le tue automazioni le vedano, così un messaggio ritentato non riceve una seconda risposta IA.
Per quanto tempo Meta continua a ritentare un webhook che non ha ricevuto HTTP 200, prima di scartarlo.
La maggior parte degli aggiornamenti Meta li raggruppa in un unico POST; Meta non garantisce il raggruppamento, quindi gestisci ogni richiesta separatamente.
Il payload più grande che un POST di webhook WhatsApp può contenere.
Per quanto tempo easyCoexistence ricorda l'id di ogni messaggio in arrivo, così un messaggio ricevuto di nuovo non avvia un'automazione due volte.
Tentativi per ogni inoltro all'URL di inoltro, ciascuno in attesa di 10 secondi per un 2xx, per circa 33 ore.
Quando Meta ritenta un webhook WhatsApp?
Ogni volta che una consegna al tuo endpoint riceve un codice HTTP diverso da 200, oppure non può essere consegnata affatto. Meta ritenta subito, poi alcune altre volte con frequenza decrescente nei 7 giorni successivi, e scarta ciò che resta non confermato dopo. I ritentativi vanno a ogni app iscritta al WhatsApp Business Account per quel campo, ed è per questo che Meta avverte che possono generare notifiche duplicate. Non esiste un'API per recuperare i webhook passati, quindi una consegna che esaurisce i suoi 7 giorni è persa per il tuo sistema.
Perché arrivano duplicati anche quando il tuo server funziona?
Perché una consegna può riuscire dal tuo lato e sembrare comunque fallita a Meta. Un gestore che esegue il lavoro prima di rispondere può superare l'attesa di Meta, quindi Meta ritenta qualcosa che hai già elaborato. Un rilascio che riavvia il server a metà di una richiesta, un load balancer che restituisce 502 per un momento, o un 201 o 204 invece di 200 contano tutti come fallimenti. I raggruppamenti aggiungono un caso in più: un solo POST può contenere molti aggiornamenti, quindi un timeout su un grande gruppo riporta indietro l'intero gruppo, inclusi gli aggiornamenti che hai già gestito.
Su quale chiave deduplicare?
Sugli id di Meta, scelti per tipo di evento, perché un messaggio produce legittimamente più webhook. Una chiave di stato senza il valore dello stato scarterebbe delivered e read come copie di sent, e una chiave di chiamata senza l'evento manterrebbe solo la prima fase di una chiamata. Salva le chiavi con un indice univoco, così due worker che gestiscono lo stesso ritentativo non possono entrambi procedere:
In che ordine arrivano i webhook?
Non necessariamente nell'ordine in cui le cose sono accadute. La documentazione di Meta non promette alcun ordine, una consegna ritentata arriva dopo quelle più recenti, e uno stato può saltare un passaggio: Meta invia read senza delivered quando un messaggio viene letto nel momento stesso in cui arriva. Quindi salva gli eventi con il loro campo timestamp, confronta uno stato per rango e non per ordine di arrivo, e lascia che un messaggio successivo del cliente prevalga su uno precedente arrivato in ritardo. Su un numero Coexistence, l'importazione una tantum della cronologia può sovrapporsi ai messaggi in tempo reale intorno all'onboarding, e l'id del messaggio è ciò che riconcilia i due.
Com'è fatto un gestore sicuro?
Quattro passaggi: verifica, rispondi esattamente 200, deduplica, poi lavora da una coda, così nulla di lento si frappone tra la richiesta di Meta e la tua risposta. Questa versione del gestore controlla X-Hub-Signature-256 con il segreto della tua app Meta; per un numero collegato tramite easyCoexistence, Meta firma con il segreto dell'app di easyCoexistence, quindi una destinazione diretta si autentica con un segreto lungo nel percorso dell'URL, oppure passa all'inoltro gestito firmato per numero.
// 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);Come gestisce easyCoexistence i ritentativi su un numero collegato?
In entrata, easyCoexistence verifica la firma di Meta, risponde 200 ed esegue le automazioni dopo la risposta, così Meta non ritenta perché una risposta IA ha impiegato qualche secondo. Ogni id di messaggio in arrivo viene conservato per 7 giorni, la lunghezza della finestra di ritentativo di Meta, e un messaggio ricevuto di nuovo viene riconosciuto e non attiva una seconda risposta automatica.
In uscita verso il tuo URL di inoltro, ogni modifica di Meta diventa una consegna con un id in X-EC-Delivery che resta uguale tra i ritentativi di inoltro: 7 tentativi in circa 33 ore, ciascuno in attesa di 10 secondi per un 2xx. Una modifica che Meta stessa riconsegna viene inoltrata di nuovo con un nuovo id di consegna, quindi deduplica anche sugli id di Meta dentro value.
Errori comuni
- Deduplicare gli stati solo sull'id. sent, delivered e read condividono il wamid, quindi la chiave deve includere anche lo stato.
- Elaborare prima di rispondere. Un gestore lento fa ritentare a Meta un lavoro che hai già svolto; rispondi 200 per primo e lavora da una coda.
- Restituire 201 o 204. La documentazione di Meta considera qualsiasi codice diverso da 200 come consegna fallita e la ritenta.
- Deduplicare gli inoltri solo su X-EC-Delivery. Una modifica che Meta riconsegna arriva con un nuovo id di consegna; tieni gli id di Meta come seconda chiave.
Gli inoltri verso il tuo server sono firmati, messi in coda e ritentati, e ogni numero è monitorato 24/7. Da US$ 9 a US$ 0,75 per numero collegato al mese, con il prezzo che scende man mano che aggiungi numeri, e i primi 3 giorni di prova gratuita.
Domande frequenti
Per quanto tempo devo conservare gli id che ho già visto?
Almeno 7 giorni, la finestra di ritentativo di Meta. Una consegna che Meta ritenta al sesto giorno deve ancora corrispondere alla sua chiave, altrimenti verrà elaborata come nuova.
Cosa succede ai messaggi dei miei clienti se il mio endpoint è giù per giorni?
Meta ritenta per un massimo di 7 giorni e poi scarta i webhook. Su un numero Coexistence le conversazioni restano nell'app WhatsApp Business sul telefono, quindi l'azienda può rispondere da lì.
Posso rieseguire i webhook che ho perso?
Non da Meta: non esiste un'API per i dati storici dei webhook. L'importazione una tantum della cronologia di un numero Coexistence viene eseguita solo all'onboarding e non può essere richiesta di nuovo per la stessa connessione.
Meta invia lo stesso aggiornamento a più di un server?
Lo invia a ogni app iscritta al WhatsApp Business Account per quel campo. Con un override di destinazione, i campi messaggi del numero vanno all'URL di override invece che al callback predefinito di quell'app.
Continua a leggere
Pronto per iniziare?
Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.
Inizia la prova gratuitaVerificato il