Webhooks¶

Status: enterprise / roadmap

Outbound webhooks are part of the enterprise control plane and are not yet a self-serve public API. For real-time events today, use the WebSocket. This page documents the model so integrations can plan for it.

Today: 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.