Webhook

Danum AI POST domain event ke endpoint kamu supaya bisa sync dengan sistem eksternal (CRM, ticketing, data warehouse).

Setup

Login dan buka Developers → Webhooks.
Klik Add webhook dan input URL endpoint HTTPS kamu.
Pilih event yang mau di-subscribe (message.received, conversation.closed, dll).
Salin secret. Hanya ditampilkan sekali. Pakai untuk verify setiap incoming request.

Verifikasi signature

Body webhook di-sign dengan HMAC-SHA256 di header X-Danum-Signature:

X-Danum-Signature: t=1700000000,v1=64hex...

Verify (Node.js):

import crypto from 'node:crypto';
 
function verify(secret: string, header: string, rawBody: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(parts.v1, 'utf8'),
    Buffer.from(expected, 'utf8'),
  );
}

Reject request kalau t lebih tua dari 5 menit untuk cegah replay attack.

Jaminan delivery

Timeout: 10 detik per attempt.
Retry: 7 kali dengan exponential backoff (30d, 1m, 2m, 5m, 15m, 1j, 24j).
Auto-disable: setelah 100 failure berturut-turut, webhook di-disable dan owner akun dapat email. Enable ulang manual.
Order: best-effort kronologis, tapi kamu wajib dedupe by event.id kalau butuh strict order.

Rotasi secret tanpa downtime

Endpoint: POST /webhooks/{id}/rotate-secret. Response berisi secret baru; secret lama tetap valid 24 jam supaya kamu punya waktu roll out value baru.

Testing

Dashboard: Developers → Webhooks → buka webhook → Test → pilih event → sample payload real di-enqueue dengan full retry.
Local dev: pakai ngrok atau smee.io untuk forward ai.numintek.com → localhost.

Katalog event

message.received — customer kirim pesan inbound
message.sent — agent (AI atau human) kirim outbound
conversation.opened — percakapan baru dimulai
conversation.closed — percakapan selesai atau ditutup
conversation.handoff — escalated ke human
customer.created — customer unik baru teridentifikasi
outcome.tagged — operator tag outcome (BOOKING, SALE, dll)

Schema lengkap per event di Referensi API.

Index Index