Ponowne próby webhooków WhatsApp, duplikaty i kolejność: jak je obsługiwać
Meta ponawia webhook WhatsApp, który dostał cokolwiek innego niż HTTP 200, najpierw od razu, potem z malejącą częstotliwością, przez maksymalnie 7 dni, a po tym czasie go porzuca. Ponowienia trafiają do każdej aplikacji subskrybującej konto, więc duplikaty są normalne. Odpowiadaj 200 szybko, deduplikuj na podstawie identyfikatora wiadomości albo identyfikatora statusu i statusu, a zdarzenia porządkuj według ich własnych znaczników czasu.
easyCoexistence łączy numer Twojej aplikacji WhatsApp Business z Cloud API Meta przez Coexistence i odfiltrowuje ponowne dostawy Meta, zanim zobaczą je Twoje automatyzacje, więc ponowiona wiadomość nie dostaje drugiej odpowiedzi AI.
Jak długo Meta ponawia webhook, który nie dostał HTTP 200, zanim go porzuci.
Większość aktualizacji Meta łączy w jedno żądanie POST; Meta nie gwarantuje grupowania, więc każde żądanie obsługuj osobno.
Największa treść żądania POST, jaką może przenieść webhook WhatsApp.
Jak długo easyCoexistence pamięta identyfikator każdej przychodzącej wiadomości, aby ponownie dostarczona wiadomość nie uruchomiła automatyzacji dwa razy.
Liczba prób na jedno przekazanie do Forward URL; każda czeka 10 sekund na odpowiedź 2xx, łącznie przez około 33 godziny.
Kiedy Meta ponawia webhook WhatsApp?
Za każdym razem, gdy dostarczenie do Twojego endpointu zwróci status HTTP inny niż 200 albo w ogóle nie może zostać dostarczone. Meta ponawia od razu, potem jeszcze kilka razy z malejącą częstotliwością w ciągu kolejnych 7 dni, a po tym czasie porzuca to, co nie zostało potwierdzone. Ponowienia trafiają do każdej aplikacji subskrybującej konto WhatsApp Business dla danego pola, dlatego Meta ostrzega, że mogą generować zduplikowane powiadomienia. Nie ma API do pobierania przeszłych webhooków, więc dostarczenie, które wyczerpie swoje 7 dni, jest dla Twojego systemu stracone.
Dlaczego duplikaty przychodzą, nawet gdy serwer działa poprawnie?
Ponieważ dostarczenie może się udać po Twojej stronie i mimo to wyglądać na nieudane dla Meta. Procedura obsługi, która wykonuje pracę przed odpowiedzią, może przekroczyć czas oczekiwania Meta, więc Meta ponawia coś, co już przetworzyłeś. Wdrożenie restartujące serwer w trakcie żądania, balanser obciążenia zwracający przez chwilę 502 albo odpowiedź 201 lub 204 zamiast 200 to wszystko błędy. Grupowanie dodaje jeszcze jeden przypadek: jedno żądanie POST może zawierać wiele aktualizacji, więc przekroczenie czasu przy dużej grupie przywraca całą grupę, łącznie z aktualizacjami, które już obsłużyłeś.
Po jakim kluczu deduplikować?
Po identyfikatorach nadanych przez Meta, dobieranych osobno dla każdego typu zdarzenia, bo jedna wiadomość legalnie generuje kilka webhooków. Klucz statusu bez wartości statusu traktowałby delivered jako kopię sent, a klucz połączenia bez typu zdarzenia zachowałby tylko pierwszy etap połączenia. Klucze przechowuj z unikalnym indeksem, tak aby dwa procesy obsługujące tę samą ponowną próbę nie mogły obie zostać przetworzone:
W jakiej kolejności przychodzą webhooki?
Niekoniecznie w kolejności, w jakiej rzeczy się wydarzyły. Dokumentacja Meta nie obiecuje żadnej kolejności, ponowiona dostawa trafia po nowszych, a status może pominąć etap: Meta wysyła read bez delivered, gdy wiadomość zostaje przeczytana w chwili dotarcia. Dlatego zapisuj zdarzenia z ich własnym polem czasu, porównuj status według rangi, a nie czasu przybycia, i pozwól, by późniejsza wiadomość klienta miała pierwszeństwo przed wcześniejszą, która przyszła spóźniona. Na numerze Coexistence jednorazowy import historii może się nakładać na wiadomości na żywo wokół wdrożenia, a identyfikator wiadomości pozwala te dwa strumienie uzgodnić.
Jak wygląda bezpieczna procedura obsługi?
Cztery kroki: weryfikacja, odpowiedź dokładnie 200, deduplikacja, a potem praca z kolejki, żeby nic wolnego nie stało między żądaniem Meta a Twoją odpowiedzią. Ta wersja sprawdza X-Hub-Signature-256 sekretem Twojej własnej aplikacji Meta; w przypadku numeru podłączonego przez easyCoexistence Meta podpisuje sekretem aplikacji easyCoexistence, więc bezpośredni cel uwierzytelnia się długim sekretem w ścieżce URL albo przechodzi na przekazywanie zarządzane z podpisem dla każdego numeru.
// 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);Jak easyCoexistence obsługuje ponowne próby na podłączonym numerze?
Przy wejściu easyCoexistence sprawdza podpis Meta, odpowiada 200 i uruchamia automatyzacje po odpowiedzi, więc Meta nie ponawia wysyłki tylko dlatego, że odpowiedź AI zajęła kilka sekund. Identyfikator każdej przychodzącej wiadomości jest przechowywany przez 7 dni, czyli tyle, ile trwa okno ponowień Meta, a ponownie dostarczona wiadomość zostaje rozpoznana i nie uruchamia drugiej automatycznej odpowiedzi.
Przy wyjściu do Twojego Forward URL każda zmiana Meta staje się jedną dostawą z identyfikatorem w X-EC-Delivery, który pozostaje taki sam przy ponowieniach przekazania: 7 prób przez około 33 godziny, każda czeka 10 sekund na 2xx. Zmiana, którą sama Meta ponownie dostarcza, zostaje przekazana ponownie pod nowym identyfikatorem dostawy, dlatego deduplikuj także po identyfikatorach Meta wewnątrz value.
Typowe błędy
- Deduplikowanie statusów tylko po identyfikatorze. sent, delivered i read mają wspólny wamid, więc klucz musi zawierać także status.
- Przetwarzanie przed odpowiedzią. Wolna procedura sprawia, że Meta ponawia pracę, którą już wykonałeś; najpierw zwróć 200, a potem pracuj z kolejki.
- Zwracanie 201 lub 204. Dokumentacja Meta traktuje każdy status inny niż 200 jako nieudaną dostawę i ponawia ją.
- Deduplikowanie przekazań tylko po X-EC-Delivery. Zmiana, którą Meta ponownie dostarcza, przychodzi pod nowym identyfikatorem dostawy; jako drugi klucz zachowaj identyfikatory Meta.
Przekazania do Twojego serwera są podpisywane, kolejkowane i ponawiane, a każdy numer jest monitorowany 24/7. Od US$ 9 do US$ 0.75 za numer miesięcznie, im więcej numerów, tym taniej, z bezpłatnym okresem próbnym przez pierwsze 3 dni.
Najczęściej zadawane pytania
Jak długo powinienem przechowywać identyfikatory, które już widziałem?
Co najmniej 7 dni, czyli okno ponowień Meta. Dostawa, którą Meta ponawia w szóstym dniu, musi nadal pasować do swojego klucza, inaczej zostanie przetworzona jako nowa.
Co się dzieje z wiadomościami moich klientów, jeśli mój endpoint nie działa przez kilka dni?
Meta ponawia przez maksymalnie 7 dni, a potem porzuca webhooki. Na numerze Coexistence rozmowy nadal są w aplikacji WhatsApp Business na telefonie, więc firma może odpowiedzieć właśnie stamtąd.
Czy mogę odtworzyć webhooki, których nie odebrałem?
Nie z poziomu Meta: nie ma API do historycznych danych webhooków. Jednorazowy import historii numeru Coexistence działa tylko przy wdrożeniu i nie da się go ponownie uruchomić dla tego samego połączenia.
Czy Meta wysyła tę samą aktualizację do więcej niż jednego serwera?
Wysyła do każdej aplikacji subskrybującej konto WhatsApp Business dla danego pola. Przy nadpisaniu celu wiadomości z pól numeru trafiają pod adres nadpisania zamiast domyślnego callbacku tej aplikacji.
Czytaj dalej
Gotowy, aby zacząć?
Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.
Rozpocznij bezpłatny okres próbnyZweryfikowano w