Permintaan Integrasi Webhook — Collection Broadcast

Ke: Tim Omnix Dari: Tim Collection Broadcast (Gadai Mulia) Tujuan: Kami butuh notifikasi real-time saat status pengiriman WhatsApp (sent/delivered/read/failed) berubah, supaya tidak perlu polling GET /api/client/collar/add-recipient/{id}/detail berulang-ulang ke sistem Omnix untuk setiap recipient.

1. Yang kami minta dari tim Omnix

Konfirmasi ketersediaan fitur — apakah Omnix/Sopiga sudah punya (atau bisa dibuatkan) mekanisme outgoing webhook saat status recipient di collar berubah? (Kami cek dokumentasi publik di /docs?api-docs.yaml dan tidak menemukan endpoint registrasi webhook untuk collar/recipient — hanya ada webhook_url di level WhatsAppSession, yang tampaknya untuk keperluan lain.)
Endpoint/cara registrasi URL callback kami ke sistem Omnix (dashboard, API, atau config manual).
Shared secret untuk signing payload (lihat §3) — dikirim lewat kanal aman (bukan email biasa), atau kalau Omnix punya skema signature sendiri (mis. HMAC dengan public key, atau format berbeda), kasih tahu kami spesifikasinya — kami sesuaikan.
Kapan callback dikirim — idealnya setiap kali status berubah (sent → delivered → read, atau → failed), bukan cuma sekali di akhir.
Retry policy di sisi Omnix — kalau endpoint kami down/timeout, apakah Omnix retry otomatis? Berapa kali, dengan interval berapa?

2. Endpoint & secret yang kami berikan ke Omnix

URL   : https://<DOMAIN_PUBLIK_KAMI>/webhooks/sopiga/delivery-status
Method: POST
Secret: (kirim terpisah lewat kanal aman — JANGAN taruh di email/chat biasa,
         JANGAN commit ke dokumen/repo ini)

⚠️ URL di atas masih placeholder — isi dengan domain publik/staging service omnix-broadcast kami sebelum dikirim ke tim Omnix. Saat ini service jalan lokal di localhost:8081, belum bisa diakses dari luar.

🔒 Secret key sudah kami generate (64 karakter hex, random 256-bit) dan tersimpan di .env service kami (WEBHOOK_SECRET). Kirim nilainya ke PIC Omnix lewat kanal aman (password manager, secret vault, atau chat terenkripsi — bukan email/Slack polos). Mereka pakai secret yang SAMA persis untuk menandatangani tiap request ke kami.

3. Format payload — dikonfirmasi tim Omnix ✅

Header:

X-Sopiga-Signature: <hex HMAC-SHA256 dari raw body, pakai secret di atas>

Body:

{
  "recipient_detail_id": 1234,
  "status": "sent",
  "gateway": "628124878787"
}

Field	Tipe	Keterangan
`recipient_detail_id`	integer	Sama dengan `recipient_detail_id` yang dikembalikan saat `add-recipient`
`status`	string	Salah satu: `pending`, `sent`, `delivered`, `read`, `failed` (atau `undelivered`)
`gateway`	string	Nomor WhatsApp pengirim (sender)

Sudah diuji end-to-end di sisi kami dengan payload persis seperti di atas — status: "sent" diabaikan (belum final), status: "delivered"/"read" update record jadi delivered, status: "failed"/"undelivered" update jadi failed.

Masih perlu dikonfirmasi: apakah header X-Sopiga-Signature (HMAC-SHA256) di atas juga dipakai Omnix, atau ada skema signature/auth lain di sisi mereka?

4. Response yang kami kirim balik

200 OK — payload diterima & diproses.
400 Bad Request — payload tidak valid/tidak bisa diparse.
401 Unauthorized — signature tidak cocok.
500 Internal Server Error — gagal proses di sisi kami (mohon di-retry).

5. Fallback

Selama callback belum aktif/terverifikasi, kami tetap jalankan polling manual ke GET /api/client/collar/add-recipient/{id}/detail sebagai cadangan, jadi tidak ada risiko data hilang selama masa transisi.

3.7 KiB Raw Permalink Blame History