Webhooks

Danum AI POSTs domain events to your endpoint so you can sync with external systems (CRM, ticketing, data warehouse).

Setup

Sign in and go to Developers → Webhooks.
Click Add webhook and enter your HTTPS endpoint URL.
Pick events to subscribe to (message.received, conversation.closed, etc).
Copy the secret. It is only shown once. Use it to verify every incoming request.

Signature verification

Every webhook body is signed with HMAC-SHA256 in the X-Danum-Signature header:

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 requests where t is older than 5 minutes to prevent replay attacks.

Delivery guarantees

Timeout: 10 seconds per delivery attempt.
Retries: 7 attempts with exponential backoff (30s, 1m, 2m, 5m, 15m, 1h, 24h).
Auto-disable: after 100 consecutive failures, the webhook is disabled and the account owner receives an email. Re-enable manually.
Order: best-effort chronological, but you must dedupe by event.id if strict order matters.

Rotate the secret without downtime

Endpoint: POST /webhooks/{id}/rotate-secret. The response contains the new secret; the old one stays valid for 24 hours to give you time to roll out the new value.

Testing

Dashboard: Developers → Webhooks → open a webhook → Test → pick an event → a real sample payload is enqueued with full retry.
Local dev: use ngrok or smee.io to forward ai.numintek.com → localhost.

Event catalog

message.received — customer sends an inbound message
message.sent — agent (AI or human) sends outbound
conversation.opened — new conversation started
conversation.closed — conversation resolved / closed
conversation.handoff — escalated to human
customer.created — new unique customer identified
outcome.tagged — operator tagged an outcome (BOOKING, SALE, etc)

Full schema per event in API Reference.

Index Index