Skip to main content
The endpoint-based webhook system lets you register multiple destinations per organization, each with its own secret, its own status, and its own subscription to a subset of event types. This is the recommended model for all new integrations. Compare to the legacy single-URL webhook, which is kept for backward compatibility but only supports one URL per org.

​
Endpoints

MethodPathRequired roleDescription
GET/v1/developer/webhook-endpointsadmin+List endpoints
POST/v1/developer/webhook-endpointsadmin+Create an endpoint
PATCH/v1/developer/webhook-endpoints/{endpoint_id}admin+Update label / URL / events / status
DELETE/v1/developer/webhook-endpoints/{endpoint_id}admin+Delete an endpoint

​
Endpoint object

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "whsec_abc…xyz12",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}
FieldTypeDescription
idUUIDEndpoint id
labelstringDisplay name, 1–120 chars
urlstringHTTPS URL; http://localhost allowed for dev
eventsarray of stringSubscribed event types (see valid values). Empty array subscribes to all events
statusstringactive, disabled (manually paused), or failing (auto-set after 24 h of non-2xx responses)
secret_hintstringLast 6 chars of the signing secret with a whsec_ prefix and ellipsis — enough to cross-reference the secret you saved locally without exposing the full value
created_at, updated_attimestamp
The endpoint’s full secret is returned once on creation and never again. Store it securely — if you lose it, delete the endpoint and recreate it.

​
Valid event types

events is validated against this exact set — values outside the list return 400. See Events catalog for each type’s payload shape.
  • telephony.incoming, telephony.complete, telephony.tool
  • web.incoming, web.complete, web.tool
  • call.graded
  • issue.reported
  • test-call.completed

​
List endpoints

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
Returns an array of Endpoint objects.

​
Create an endpoint

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

​
Request fields

FieldTypeRequiredDescription
labelstringyes1–120 chars
urlstringyesHTTPS URL
eventsarraynoEmpty/omitted subscribes to all events. Must use the values listed in Valid event types
Returns 201 Created with the Endpoint object plus an extra top-level secret field containing the raw signing key: 
{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "whsec_abc…xyz12",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "whsec_abc1234567890abcdef1234567890abcdef"
}
secret is returned only on creation. Subsequent GET responses include only the secret_hint. Copy the full value to your secret manager before dismissing the response.

​
Update an endpoint

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'
FieldTypeDescription
labelstring
urlstring
eventsarray
statusstringactive or disabled (to pause); failing is only set by the server
Returns 200 OK with the updated Endpoint object.

​
Delete an endpoint

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
Returns 204 No Content. Delivery to the URL stops immediately; in-flight retries are abandoned.

Events catalog

The full list of events values you can subscribe to.

Webhooks overview

Signature verification and delivery semantics.