Webhooks

Status: gated until launch

Self-serve developer webhooks exist — GET/POST/DELETE /v1/developer/webhooks plus GET /v1/developer/webhook-events — but the whole external developer surface is gated behind apikey_auth_enabled and is off in production until launch (the same flag as the rest of the platform). Until it flips, use the WebSocket for real-time events. This page documents both.

Self-serve developer webhooks

Once the platform flag is on, manage endpoints from the developer console or the API. The webhooks:manage scope is required.

Method	Path	Purpose
GET	/v1/developer/webhooks	List your registered endpoints.
POST	/v1/developer/webhooks	Register an endpoint (an HTTPS URL + the event types you want).
DELETE	/v1/developer/webhooks/{id}	Remove an endpoint.
GET	/v1/developer/webhook-events	The catalog of event types you can subscribe to.

Registration URLs are validated against an SSRF guard (no metadata IPs, RFC1918/loopback/CGNAT, https-only in prod), and delivery re-pins the resolved IP to defeat DNS-rebinding.

Meanwhile: use the WebSocket

For server-driven applications that need push, the canonical mechanism is the WebSocket at /v1/ws. It carries the full server→client event catalog (new messages, read receipts, presence, call signaling, AI progress) with at-least-once delivery and a reconnect/replay path.

If you cannot hold a socket open, poll the relevant list endpoints with the after=<timestamp> window — see Pagination.

Delivery model (enterprise)

The platform has an internal webhook delivery subsystem (webhook_endpoints + webhook_deliveries) used by the operator/control-plane surface. Its delivery semantics — which the public webhook product will inherit — are:

• At-least-once delivery with retries and a dead-letter path. Your receiver must be idempotent: dedupe on the event id.
• Ordered per subject where ordering matters (e.g. per thread/message), best effort across subjects.
• Signed payloads so you can verify authenticity before acting.

A typical delivery envelope mirrors the WebSocket event envelope:

{
  "id": "evt_…",
  "type": "message.new",
  "created_at": "2026-05-24T19:05:00Z",
  "data": { }
}

Designing a receiver now

Even before public webhooks ship, build your receiver to these rules so the switch is a no-op:

• Verify the signature on every request before trusting the body.
• Return 2xx fast, then process asynchronously. Slow receivers get retried and may be disabled.
• Be idempotent — store processed event ids and ignore duplicates.
• Tolerate unknown types — new event types are additive.

Want webhooks for your integration?

Webhook registration is part of the Voice Cloud API roadmap. Reach out to developers@telbox.ai to register interest and influence the event set.