Panduan Webhook WhatsApp: Event, Keamanan, dan Retry

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

Bagaimana menulis handler yang andal?

Lakukan tiga hal secara berurutan: simpan event mentah, konfirmasi dengan 2xx, lalu proses secara asinkron. Handler di bawah mengikuti pola dalam dokumentasi kami.

import express from "express";

const app = express();

// Tangkap body mentah agar dapat disimpan persis seperti yang diterima.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // penyimpanan gagal: biarkan event dicoba ulang
    }
    res.sendStatus(200);          // konfirmasi dengan cepat
    queue.publish("status-events", req.body); // kerjakan pekerjaan sebenarnya di tempat lain
  },
);

// Worker: pemrosesan idempoten
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // petakan per kanal
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // pesan tidak dikenal: catat dan selidiki
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // duplikat atau usang

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # penyimpanan gagal: biarkan event dicoba ulang
    queue.publish("status-events", raw)  # proses secara asinkron
    return "", 200               # konfirmasi dengan cepat

Objek db dan queue adalah penyimpanan dan antrean job milik Anda sendiri. Peta rank yang membuat pemrosesan idempoten: event duplikat atau usang bukan kemajuan, sehingga diabaikan.

Aturan untuk handler yang andal

• Respons dalam beberapa detik. Jangan lakukan pekerjaan berat sebelum merespons.
• Kembalikan 2xx hanya setelah event tersimpan. Jika penyimpanan gagal, kembalikan 5xx.
• Deduplikasi berdasarkan ID pesan. Status yang sama dapat tiba lebih dari sekali.
• Jangan pernah mengirim ulang pesan dari handler. Putuskan retry dalam job terpisah, setelah memeriksa status.
• Simpan body mentah untuk troubleshooting dan untuk memutar ulang event setelah perbaikan.

Bagaimana mengamankan webhook WhatsApp?

Tergantung siapa yang mengirim ke endpoint Anda. Meta menandatangani webhook yang dikirimnya ke aplikasi yang Anda daftarkan di Meta. Spesifikasi API OmniChannels.ai tidak mendefinisikan header tanda tangan webhook, jadi jangan menunggunya.

Untuk skema Meta, dokumentasi Meta menyatakan untuk membuat hash HMAC-SHA256 dari payload JSON memakai app secret Anda dan membandingkannya dengan nilai setelah sha256= pada header X-Hub-Signature-256. HMAC sendiri didefinisikan dalam RFC 2104. Hitung atas byte mentah, bukan objek yang diserialisasi ulang, dan bandingkan dalam waktu konstan.

Untuk endpoint kami:

• Gunakan HTTPS saja, dengan sertifikat yang valid.
• Gunakan path yang panjang dan tidak dapat ditebak, dan ganti jika bocor.
• Validasi bentuk body dan tolak apa pun yang tidak terduga.
• Perlakukan event sebagai notifikasi. Sebelum tindakan yang tidak dapat dibatalkan, seperti pengembalian dana atau penguncian fraud, konfirmasikan statusnya dengan panggilan polling.

Apa yang terjadi ketika pengiriman gagal?

Retry bergantung pada pengirim. Dokumentasi Meta menyatakan Meta mengulang pengiriman yang gagal dengan frekuensi yang menurun hingga 7 hari, yang dapat menghasilkan notifikasi duplikat. Itu alasan untuk idempoten meskipun Anda jarang melihat duplikat. Untuk event dari platform kami, konfirmasikan perilaku retry kepada onboarding engineer Anda dan jangan berasumsi sama dengan Meta.

Bagaimanapun, bangunlah untuk kehilangan dan juga duplikasi: endpoint Anda bisa mati saat deploy, dan aturan firewall dapat membuang request secara diam-diam.

Bagaimana memulihkan event yang hilang?

Poll batch-nya, jangan kirim ulang pesannya.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id adalah ID yang dikembalikan panggilan pengiriman, dan page dimulai dari nol. Jalankan rekonsiliasi malam hari yang membaca batch hari sebelumnya dan mengisi celah apa pun.

Checklist troubleshooting

1. Apakah URL dikonfigurasi di akun atau sub-akun yang benar?
2. Apakah endpoint dapat dijangkau melalui HTTPS dengan sertifikat valid?
3. Apakah endpoint menjawab 2xx dengan cepat, atau timeout?
4. Apakah aturan firewall atau WAF memblokir request?
5. Apakah Anda mencatat body mentah sebelum parsing, agar error parser tidak menyembunyikan event?

Contoh kasus: pipeline notifikasi pengecer

"Souq Rafiq" (fiktif), pengecer di UEA, mengirim pembaruan pesanan lewat WhatsApp dan menginginkan status yang akurat di alat pesanannya.

1. Pesanan dikirim dengan sendbulk, dan batchId disimpan pada pesanan. Lihat kirim pesan WhatsApp via API.
2. Endpoint webhook menulis setiap event ke tabel, lalu mengembalikan 200.
3. Worker memberi peringkat status dan memperbarui status pesan pada pesanan.
4. Event FAILED membuat tugas untuk dukungan beserta alasannya, dan fallback SMS dipertimbangkan sesuai fallback kanal.
5. Pesan masuk pelanggan diarahkan ke kotak masuk bersama agar agen dapat membalas di dalam jendela.
6. Job malam hari memanggil bulk-insights untuk batch kemarin dan memperbaiki apa pun yang terlewat.

Apa saja kesalahan umum?

• Pekerjaan berat sebelum merespons, yang menyebabkan timeout dan pengiriman berulang.
• Mengonfirmasi sebelum menyimpan, yang menghilangkan event saat penyimpanan gagal.
• Memercayai urutan. SENT yang terlambat menimpa DELIVERED.
• Menulis kode berdasarkan payload ilustrasi alih-alih event nyata.
• Menyerialisasi ulang JSON sebelum memeriksa tanda tangan, yang mengubah byte-nya.
• Mengirim ulang dari handler, yang dapat berulang tanpa henti.
• Batasan: panduan ini menjelaskan perilaku yang terdokumentasi di kami. Kebijakan retry dan field payload untuk akun Anda sebaiknya dikonfirmasi saat onboarding.

Bagaimana OmniChannels.ai membantu

OmniChannels.ai mengirim (push) status pengiriman dan pesan masuk untuk WhatsApp, SMS, RCS, dan kanal lain ke webhook Anda dalam satu format ternormalisasi, dengan webhook terpisah per sub-akun bagi reseller. BroadNet adalah Meta Business Solution Provider resmi, sehingga persyaratan webhook Meta sendiri sudah ditangani untuk Anda, dan Anda bekerja dengan API kami. Baca referensi webhook dan dokumentasi WhatsApp API, atau lihat bagaimana event tampil di kotak masuk bersama.