Webhooks

Subscribe to account events (SMS, calls, transcriptions, and more).

• Base path: https://api.account.telebroad.com/api/public/v1
• Auth header: Authorization: Bearer ACCESS_TOKEN — see Authentication
• Scopes: webhooks:read to view, webhooks:write to change

Endpoints

Method & path	Scope
GET /webhooks	webhooks:read
GET /webhooks/types	webhooks:read
GET /webhooks/{id}	webhooks:read
POST /webhooks	webhooks:write
PUT or PATCH /webhooks/{id}	webhooks:write
DELETE /webhooks/{id}	webhooks:write
POST /webhooks/{id}/enable	webhooks:write
POST /webhooks/{id}/disable	webhooks:write

PUT and PATCH both merge — fields you omit are left unchanged. There is no replace-everything variant.

Enable and disable are POST, not GET: a GET that changes state is cacheable and prefetchable, so a proxy or link-preview bot could flip your subscription.

The webhook object

{
  "id": 2074,
  "name": "real time",
  "description": "",
  "url": "https://example.com/hook",
  "type": "AccountRealTimeCalls",
  "enabled": true,
  "createdAt": "2026-08-05T12:00:00Z",
  "updatedAt": "2026-08-05T12:00:00Z"
}

There is no customerId: the credential already determines the account.

type must be one of the values from GET /webhooks/types — currently AccountRealTimeCalls, AccountEndedCalls, UserEndedCalls, AccountSMS, AccountAITranscription. An unknown type is rejected, rather than saved as a subscription that silently never fires.

Examples

List (webhooks:read):

curl https://api.account.telebroad.com/api/public/v1/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Optional filters: ?type=AccountSMS, ?enabled=true.

Create (webhooks:write) — returns 201 with a Location header:

curl -X POST https://api.account.telebroad.com/api/public/v1/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"My hook","url":"https://example.com/hook","type":"AccountSMS","enabled":true}'

enabled defaults to false, so a half-configured integration cannot start firing at an endpoint that is not ready.

Disable, then delete (204, no body):

curl -X POST   https://api.account.telebroad.com/api/public/v1/webhooks/2074/disable -H "Authorization: Bearer $ACCESS_TOKEN"
curl -X DELETE https://api.account.telebroad.com/api/public/v1/webhooks/2074        -H "Authorization: Bearer $ACCESS_TOKEN"

Responses and errors

Success is wrapped as { "data": … }. Errors use:

{ "error": { "type": "insufficient_scope", "message": "…", "scope": "webhooks:write" } }

Branch on error.type, never on error.message — the message may change.

Status	type
400	invalid_request — missing/malformed field, or an unknown type
401	unauthenticated
403	insufficient_scope — the scope field names what to request
404	not_found

Unknown fields in a request body are rejected, so a typo gets a 400 rather than being silently ignored.