Skip to content
Telfluentטלפלואנט ישראל
English

Developers

Webhooks

Connect your software to updates about calls, minutes and workers. The endpoint must use HTTPS. Its signing secret is shown once.

Operations

Each is POST /v1/ops/{name} with JSON and an owner key (Authorization: Bearer <key>). A helper key cannot manage endpoints.

  • webhook.create { "url": "https://your-domain.example/events", "events": ["call.ended"] } (events optional: all when left out). Answer { "id", "url", "events", "secret", "created_at" }. HTTPS on port 443 only, a domain name, no credentials, query or fragment; it must resolve to public addresses. The secret is in this answer only.
  • webhook.list {}. Answer { "endpoints": [{ "id", "url", "events", "created_at" }] }: active endpoints, never a secret.
  • webhook.update { "endpoint_id", "events" } (one or more, no repeats). Answer { "id", "events" }. A newly chosen event is sent from then on, never for the past.
  • webhook.rotate { "endpoint_id" }. Answer { "id", "secret" }: the new secret, once; the old one signs nothing from then on.
  • webhook.revoke { "endpoint_id" }. Answer { "revoked" }.

Refusals come as { error: { code, message }, request_id }: invalid_input (400) for a URL that is not allowed, rejected (409) when the endpoint limit is reached or the URL is already registered, not_found (404) for an endpoint that is not this account's.

Events

Each delivery is a JSON POST with the headers x-telfluent-event-id: evt_<id> and x-telfluent-signature: t=<Unix milliseconds>,v1=<hex HMAC-SHA256>. The HMAC input is the timestamp, a dot, then the exact raw body; the key is the endpoint's secret. Compare in constant time, reject an old timestamp, and deduplicate by event id.

Body: { "id": "evt_<id>", "type": "<event>", "data": { ... } }. An endpoint receives only the events it chose.

  • call.ended: data.call_id.
  • minutes.low: data.remaining_minutes, data.period_start; once a billing period.
  • worker.joined: data.worker_id.

Delivery is at least once and may be out of order. A 2xx answer acknowledges; anything else, a redirect included, is retried with growing waits, a limited number of times over about a day. Each attempt waits at most 10 seconds. No audio, transcript, payment detail or another account's data is ever in an event.