omnix-sopiga/docs/webhook_integration_request.md

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

1. 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.)
2. Endpoint/cara registrasi URL callback kami ke sistem Omnix (dashboard, API, atau config manual).
3. 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.
4. Kapan callback dikirim — idealnya setiap kali status berubah (sent → delivered → read, atau → failed), bukan cuma sekali di akhir.
5. 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.