Webhooks

In development

Customer webhooks are not yet available. This page documents the planned design so you can architect your integration ahead of GA. The event names, payload shapes, and signing scheme below may change before launch. Contact us if you want early access or want to influence the event catalog.

Webhooks let DIDHub push events to your server in real time instead of you polling the API. You register an HTTPS endpoint; DIDHub POSTs a signed JSON payload whenever a subscribed event occurs.

How it will work

1. Register an endpoint (dashboard or POST /v1/webhooks) with a URL and the list of event types you want.
2. DIDHub returns a signing secret (whsec_…), shown once.
3. On each event, DIDHub POSTs the payload to your URL with an X-DIDHub-Signature header.
4. You verify the signature (HMAC-SHA256 over the raw body using your signing secret), then process the event.
5. Respond 2xx within 5 seconds. Non-2xx or timeout → DIDHub retries with exponential backoff for up to 24 hours.

Planned event catalog

Event	Fires when
number.provisioned	A number order completes and the DID becomes active
number.suspended	A number is suspended (e.g. non-payment, compliance)
number.released	A number is released back to inventory
call.completed	A call ends and its CDR is written
sms.received	An inbound SMS arrives on one of your numbers
compliance.bundle.approved	A submitted compliance bundle is approved
compliance.bundle.rejected	A bundle is rejected (with reviewer notes)
billing.recharge.succeeded	An auto-recharge top-up completes
billing.recharge.failed	An auto-recharge attempt fails
port.status_changed	A number-porting request changes state

Planned payload shape

{
  "id": "evt_example_abc123",
  "type": "call.completed",
  "created_at": 1716500000,
  "data": {
    "cdr_id": "cdr_example_abc123",
    "direction": "inbound",
    "e164": "+15550100200",
    "billable_duration_s": 42,
    "customer_total_cents": 7
  }
}

Planned signature verification

X-DIDHub-Signature: t=1716500000,v1=5257a8...

v1 is HMAC-SHA256(secret, "{t}.{raw_body}") hex-encoded. Verify the timestamp is recent (within ~5 minutes) to prevent replay, then constant-time-compare the signature.

Until webhooks ship

Poll the relevant read endpoints:

• Calls: GET /v1/cdrs?from={unix} on an interval
• Number status: GET /v1/numbers and watch the status field
• Billing: GET /v1/billing/transactions

See the interactive API explorer for these endpoints today.