Percobaan ulang, duplikat, dan urutan webhook WhatsApp: cara menanganinya
Meta mengulang webhook WhatsApp yang tidak menerima HTTP 200, segera lalu dengan frekuensi yang makin jarang hingga 7 hari, dan membuangnya setelah itu. Percobaan ulang dikirim ke setiap aplikasi yang berlangganan ke akun, jadi duplikat itu wajar. Balas 200 dengan cepat, lakukan deduplikasi berdasarkan id pesan atau id status ditambah status, dan urutkan event berdasarkan timestamp masing-masing.
easyCoexistence menghubungkan nomor aplikasi WhatsApp Business Anda ke Cloud API Meta melalui Coexistence dan menyerap pengiriman ulang Meta sebelum otomasi Anda melihatnya, sehingga pesan yang diulang tidak mendapat balasan AI kedua.
Berapa lama Meta terus mengulang webhook yang tidak menerima HTTP 200, sebelum membuangnya.
Meta mengirim sebagian besar pembaruan sekaligus dalam satu POST; Meta tidak menjamin pengelompokan, jadi tangani setiap permintaan secara terpisah.
Ukuran payload terbesar yang dapat dibawa oleh satu POST webhook WhatsApp.
Berapa lama easyCoexistence menyimpan setiap id pesan masuk, agar pesan yang dikirim ulang tidak menjalankan otomasi dua kali.
Percobaan per penerusan ke Forward URL Anda, masing-masing menunggu 10 detik untuk 2xx, selama sekitar 33 jam.
Kapan Meta mengulang webhook WhatsApp?
Setiap kali pengiriman ke endpoint Anda menerima status HTTP selain 200, atau sama sekali tidak dapat dikirim. Meta langsung mengulang, lalu beberapa kali lagi dengan frekuensi yang makin jarang selama 7 hari berikutnya, dan membuang yang belum dikonfirmasi setelah itu. Percobaan ulang dikirim ke setiap aplikasi yang berlangganan WhatsApp Business Account untuk field tersebut, sehingga Meta memperingatkan bahwa hal ini dapat menghasilkan notifikasi duplikat. Tidak ada API untuk mengambil webhook masa lalu, jadi pengiriman yang habis masa 7 harinya hilang dari sistem Anda.
Mengapa duplikat tetap datang saat server Anda sehat?
Karena pengiriman bisa berhasil di sisi Anda tetapi tetap terlihat gagal bagi Meta. Handler yang mengerjakan tugas sebelum menjawab bisa melewati batas tunggu Meta, sehingga Meta mengulang sesuatu yang sudah Anda proses. Deploy yang memulai ulang server di tengah permintaan, load balancer yang mengembalikan 502 sesaat, atau 201 atau 204 alih-alih 200, semuanya dihitung sebagai kegagalan. Batch menambah satu kasus lagi: satu POST bisa memuat banyak pembaruan, jadi timeout pada batch besar mengembalikan seluruh batch, termasuk pembaruan yang sudah Anda tangani.
Kunci mana yang harus dipakai untuk deduplikasi?
Id milik Meta sendiri, dipilih per jenis event, karena satu pesan secara sah menghasilkan beberapa webhook. Kunci status tanpa nilai status akan membuang delivered dan read karena dianggap salinan sent, dan kunci panggilan tanpa event hanya menyimpan tahap pertama panggilan. Simpan kunci-kunci tersebut dengan unique index, agar dua worker yang menangani percobaan ulang yang sama tidak bisa sama-sama lolos:
Dalam urutan apa webhook tiba?
Belum tentu sesuai urutan kejadiannya. Dokumentasi Meta tidak menjanjikan urutan, pengiriman yang diulang tiba setelah yang lebih baru, dan status bisa melompati satu tahap: Meta mengirim read tanpa delivered saat pesan dibaca begitu tiba. Maka simpan event dengan field timestamp-nya sendiri, bandingkan status berdasarkan peringkat, bukan waktu tiba, dan biarkan pesan pelanggan yang lebih baru mengalahkan pesan lebih lama yang terlambat tiba. Pada nomor Coexistence, impor riwayat satu kali bisa tumpang tindih dengan pesan live di sekitar onboarding, dan id pesanlah yang merekonsiliasi keduanya.
Seperti apa handler yang aman?
Empat langkah: verifikasi, jawab tepat 200, lakukan deduplikasi, lalu kerjakan dari antrean, sehingga tidak ada proses lambat di antara permintaan Meta dan respons Anda. Versi ini memeriksa X-Hub-Signature-256 dengan secret aplikasi Meta Anda sendiri; untuk nomor yang terhubung melalui easyCoexistence, Meta menandatangani dengan secret aplikasi easyCoexistence, sehingga tujuan langsung melakukan autentikasi dengan secret panjang di path URL-nya, atau beralih ke penerusan terkelola yang ditandatangani per nomor.
// 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);Bagaimana easyCoexistence menangani percobaan ulang pada nomor yang terhubung?
Pada sisi masuk, easyCoexistence memeriksa tanda tangan Meta, menjawab 200, dan menjalankan otomasi setelah respons, sehingga Meta tidak mengulang karena balasan AI butuh beberapa detik. Setiap id pesan masuk disimpan selama 7 hari, sama dengan jendela percobaan ulang Meta, dan pesan yang dikirim ulang dikenali serta tidak memicu balasan otomasi kedua.
Pada sisi keluar ke Forward URL Anda, setiap perubahan Meta menjadi satu pengiriman dengan id di X-EC-Delivery yang tetap sama di seluruh percobaan penerusan: 7 percobaan selama sekitar 33 jam, masing-masing menunggu 10 detik untuk 2xx. Perubahan yang dikirim ulang oleh Meta sendiri diteruskan lagi dengan id pengiriman baru, jadi lakukan deduplikasi juga berdasarkan id Meta di dalam value.
Kesalahan umum
- Melakukan deduplikasi status hanya dengan id. sent, delivered dan read berbagi wamid, jadi kuncinya harus menyertakan status juga.
- Memproses sebelum menjawab. Handler yang lambat membuat Meta mengulang pekerjaan yang sudah Anda lakukan; kembalikan 200 dulu lalu kerjakan dari antrean.
- Mengembalikan 201 atau 204. Dokumentasi Meta memperlakukan status selain 200 sebagai pengiriman gagal dan mengulangnya.
- Melakukan deduplikasi penerusan hanya dengan X-EC-Delivery. Perubahan yang dikirim ulang oleh Meta datang dengan id pengiriman baru; simpan id Meta sebagai kunci kedua.
Penerusan ke server Anda ditandatangani, dimasukkan ke antrean, dan dicoba kembali, serta setiap nomor dipantau 24/7. Dari US$ 9 turun ke US$ 0.75 per nomor per bulan, makin turun seiring bertambahnya nomor, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Berapa lama saya harus menyimpan id yang sudah pernah saya lihat?
Minimal 7 hari, sama dengan jendela percobaan ulang Meta. Pengiriman yang diulang Meta pada hari keenam harus tetap cocok dengan kuncinya, atau akan diproses sebagai pengiriman baru.
Apa yang terjadi pada pesan pelanggan saya jika endpoint saya mati berhari-hari?
Meta mengulang hingga 7 hari lalu membuang webhook. Pada nomor Coexistence, percakapannya tetap ada di aplikasi WhatsApp Business di ponsel, sehingga bisnis dapat membalas dari sana.
Bisakah saya memutar ulang webhook yang terlewat?
Tidak dari Meta: tidak ada API untuk data webhook historis. Impor riwayat satu kali pada nomor Coexistence hanya berjalan saat onboarding dan tidak bisa diminta lagi untuk koneksi yang sama.
Apakah Meta mengirim pembaruan yang sama ke lebih dari satu server?
Meta mengirim ke setiap aplikasi yang berlangganan WhatsApp Business Account untuk field tersebut. Dengan override tujuan, field pesan nomor dikirim ke URL override, bukan ke callback default aplikasi itu.
Lanjut membaca
Siap memulai?
Konfigurasikan WhatsApp Coexistence dalam hitungan menit, bukan bulan. Aplikasi tetap berfungsi di ponsel.
Mulai uji coba gratisDiverifikasi pada