Create a webhook subscription

Creates a webhook subscription on your account: a URL you register to be called when a chosen call event happens. A subscription fires on exactly one event — event_trigger must be one of New Call, Ringing, Call Answer, Call Hangup or Fax Content, any other value is stored but never fires — and only a request_type of POST is ever delivered: one HTTPS request to request_url with Content-Type: application/json and a body of exactly {"eventType": "<trigger>"}, with no call ID, phone numbers, timestamp or account in it. There is no signature, delivery ID, retry or delivery log, and custom headers in header_json are stored but not sent — still, set header_json to {} rather than leaving it null, because a null value stops that event from being delivered to any subscription on your account. The new subscription starts enabled whatever you send for enabled, and its ID is not returned: the response body is an empty object, so list your subscriptions to find it.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required

Display name for the subscription. Required. It is returned as name by the single-subscription read and as webhook_name by the list.

string | null

Optional free-text note about what the subscription is for.

string
required

Required. The call event that fires this subscription: New Call, Ringing, Call Answer, Call Hangup or Fax Content. Any other value is accepted but never fires.

event_trigger_filters
object | null

Optional object. Stored and returned with the subscription but not applied when events are delivered.

string | null
enum

POST, PUT or DELETE; anything else is rejected with 400. Only POST is delivered — a PUT or DELETE subscription never calls your URL.

Allowed:
string
required

Required. The URL that receives the event. It is not validated when you create the subscription.

header_json
object | null

Optional object of header names to values. It is stored and returned in clear — including any Authorization value — but is not sent with the request. Send {} rather than null: a null value blocks delivery of that event to every subscription on your account.

string
enum

default_payload (the default), x-www-form-urlencoded, raw or web_push; anything else is rejected with 400. Only web_push changes anything — it routes the event to a push-notification service instead of request_url. The others all send the same JSON body.

Allowed:
body_payload_json
object | null

Optional object. Stored and returned with the subscription but never used in the delivered request.

boolean

Ignored on create; every new subscription starts enabled. Use the update call to disable it.

boolean
string
string
string
Responses
200

The subscription was created. The body is an empty object; list your subscriptions to get its ID.

401

Missing or invalid API key.

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json