WhatsApp webhook'larında yeniden deneme, yinelenen olaylar ve sıra: nasıl ele alınır
Meta, HTTP 200 dışında herhangi bir yanıt alan WhatsApp webhook'unu hemen, ardından giderek seyrekleşen aralıklarla 7 güne kadar yeniden dener, sonra düşürür. Yeniden denemeler, hesaba abone olan her uygulamaya gider, bu yüzden yinelenen olaylar normaldir. 200'ü hızlıca yanıtlayın, mesaj kimliğine ya da durum kimliği ile durum değerine göre tekilleştirin ve olayları kendi zaman damgalarına göre sıralayın.
easyCoexistence, WhatsApp Business uygulamanızın numarasını Coexistence üzerinden Meta'nın Cloud API'sine bağlar ve Meta'nın yeniden iletimlerini otomasyonlarınız görmeden önce süzer; böylece yeniden denenen bir mesaj ikinci bir yapay zekâ yanıtı almaz.
Meta'nın HTTP 200 almayan bir webhook'u düşürmeden önce ne kadar süre yeniden denediği.
Meta çoğu güncellemeyi tek bir POST'ta toplar; toplamayı garanti etmez, bu yüzden her isteği ayrı ele alın.
Bir WhatsApp webhook POST'unun taşıyabileceği en büyük payload boyutu.
easyCoexistence'ın her gelen mesaj kimliğini ne kadar süre hatırladığı; böylece yeniden iletilen bir mesaj otomasyonu iki kez çalıştırmaz.
Forward URL'sine her iletim için kaç deneme yapıldığı; her deneme 2xx yanıtı için 10 saniye bekler ve toplamda yaklaşık 33 saat sürer.
Meta bir WhatsApp webhook'unu ne zaman yeniden dener?
Uç noktanıza yapılan bir teslimat HTTP 200 dışında bir durumla yanıtlandığında ya da hiç iletilemediğinde. Meta hemen yeniden dener, ardından sonraki 7 gün boyunca giderek seyrekleşen aralıklarla birkaç kez daha dener; bundan sonra hâlâ onaylanmamış olanları düşürür. Yeniden denemeler, o alan için WhatsApp Business Account'a abone olan her uygulamaya gider. Meta bu yüzden yinelenen bildirim üretebileceği konusunda uyarır. Geçmiş webhook'ları getiren bir API yoktur, dolayısıyla 7 günü dolan bir teslimat sisteminizde kaybolur.
Sunucunuz sağlıklı olsa da neden yinelenen olaylar gelir?
Çünkü bir teslimat sizin tarafınızda başarılı olabilir ama Meta'ya başarısız görünebilir. Yanıt vermeden önce işini yapan bir işleyici Meta'nın bekleme süresini aşabilir; böylece Meta zaten işlediğiniz bir şeyi yeniden dener. Sunucuyu istek ortasında yeniden başlatan bir dağıtım, bir an için 502 dönen bir yük dengeleyici ya da 200 yerine 201 veya 204 dönmesi de hata sayılır. Toplu gönderimler bir durum daha ekler: tek bir POST birçok güncelleme taşıyabilir, bu yüzden büyük bir toplu istekte zaman aşımı, işlediğiniz güncellemeler dahil bütün toplu isteği geri getirir.
Hangi anahtarla tekilleştirmelisiniz?
Meta'nın kendi kimlikleriyle; her olay türü için ayrı seçilir, çünkü tek bir mesaj meşru olarak birkaç webhook üretir. Durum değeri olmayan bir durum anahtarı, delivered ile read öğelerini sent'in kopyası sayıp düşürür; olay olmayan bir çağrı anahtarı ise çağrının yalnızca ilk aşamasını tutar. Anahtarları benzersiz bir indeksle saklayın, böylece aynı yeniden denemeyi işleyen iki çalışandan yalnızca biri kazanabilir:
Webhook'lar hangi sırayla gelir?
Olanların gerçekleştiği sırayla değil, belki de. Meta sıra konusunda hiçbir garanti vermez; yeniden denenen bir teslimat daha yeni olanlardan sonra gelir ve bir durum bir adımı atlayabilir: bir mesaj geldiği anda okunduğunda Meta delivered olmadan read gönderir. Bu yüzden olayları kendi zaman damgası alanlarıyla saklayın, durumları gelme sırasına göre değil sıra değerine göre karşılaştırın ve zaman damgasında daha sonra olan bir müşteri mesajının, geç gelen daha eski bir mesaja üstün gelmesine izin verin. Coexistence numarasında tek seferlik geçmiş içe aktarımı, kurulum sırasında canlı mesajlarla çakışabilir; ikisini uzlaştıran şey mesaj kimliğidir.
Güvenli bir işleyici nasıl görünür?
Dört adım: doğrulayın, tam olarak 200 yanıtı verin, tekilleştirin, sonra bir kuyruktan çalışın; böylece Meta'nın isteğiyle yanıtınız arasında yavaş hiçbir şey olmaz. Bu sürüm X-Hub-Signature-256 değerini kendi Meta uygulamanızın gizli anahtarıyla doğrular. easyCoexistence üzerinden bağlanan bir numara için Meta, easyCoexistence'ın uygulama gizli anahtarıyla imzalar; bu yüzden doğrudan hedef, URL yolundaki uzun bir gizli anahtarla kimlik doğrular ya da numara başına imzalanan yönetilen yönlendirmeye geçer.
// 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);easyCoexistence bağlı bir numarada yeniden denemeleri nasıl yönetir?
Gelen tarafta easyCoexistence, Meta'nın imzasını denetler, 200 yanıtı verir ve otomasyonları yanıttan sonra çalıştırır; böylece bir yapay zekâ yanıtı birkaç saniye sürdü diye Meta yeniden denemez. Her gelen mesaj kimliği Meta'nın yeniden deneme penceresinin uzunluğu olan 7 gün boyunca saklanır; yeniden iletilen bir mesaj tanınır ve ikinci bir otomasyon yanıtı tetiklemez.
Forward URL'sine giden tarafta, her Meta değişikliği X-EC-Delivery içinde bir kimliği olan tek bir iletime dönüşür; bu kimlik iletim yeniden denemelerinde aynı kalır: yaklaşık 33 saat içinde 7 deneme, her biri 2xx için 10 saniye bekler. Meta'nın kendisi yeniden ilettiği bir değişiklik, yeni bir iletim kimliğiyle tekrar iletilir; bu yüzden value içindeki Meta kimliklerine göre de tekilleştirin.
Yaygın hatalar
- Durumları yalnızca id ile tekilleştirmek. sent, delivered ve read aynı wamid'i paylaşır, bu yüzden anahtarda durum da olmalıdır.
- Yanıt vermeden işlemek. Yavaş bir işleyici, Meta'nın zaten yaptığınız işi yeniden denemesine yol açar; önce 200 dönün ve kuyruktan çalışın.
- 201 ya da 204 dönmek. Meta'nın dokümantasyonu 200 dışındaki her durumu başarısız teslimat sayar ve yeniden dener.
- Forward'ları yalnızca X-EC-Delivery'ye göre tekilleştirmek. Meta'nın yeniden ilettiği bir değişiklik yeni bir iletim kimliğiyle gelir; Meta kimliklerini ikinci anahtar olarak tutun.
Sunucunuza giden iletimler imzalanır, kuyruğa alınır ve yeniden denenir; her numara 7 gün 24 saat izlenir. Numara başına aylık US$ 9'dan US$ 0,75'e iner; numara ekledikçe düşer ve ilk 3 gün ücretsiz deneme sunulur.
Sık sorulan sorular
Daha önce gördüğüm kimlikleri ne kadar süre saklamalıyım?
En az 7 gün; Meta'nın yeniden deneme penceresi bu. Meta'nın altıncı gün yeniden denediği bir teslimat hâlâ anahtarıyla eşleşmelidir, yoksa yeni olarak işlenir.
Sunucum birkaç gün çalışmazsa müşterilerimin mesajlarına ne olur?
Meta 7 güne kadar yeniden dener, sonra webhook'ları düşürür. Coexistence numarasında konuşmalar hâlâ telefondaki WhatsApp Business uygulamasındadır, bu yüzden işletme oradan yanıtlayabilir.
Kaçırdığım webhook'ları yeniden oynatabilir miyim?
Meta'dan hayır: geçmiş webhook verileri için bir API yoktur. Coexistence numarasının tek seferlik geçmiş içe aktarımı yalnızca kurulumda çalışır ve aynı bağlantı için yeniden istenemez.
Meta aynı güncellemeyi birden fazla sunucuya gönderir mi?
Bu alan için WhatsApp Business Account'a abone olan her uygulamaya gönderir. Bir hedef geçersiz kılma ile numaranın mesaj alanları, o uygulamanın varsayılan geri çağırma adresi yerine geçersiz kılma URL'sine gider.
Okumaya devam edin
Başlamaya hazır mısınız?
WhatsApp Coexistence'ı aylar değil, dakikalar içinde kurun. Uygulama telefonda çalışmaya devam eder.
Ücretsiz denemeyi başlatınDoğrulama tarihi