Webhooks

Get notified the instant something happens — a call comes in, a voicemail is left, or a transcription finishes. Register a URL once, pick the events you care about, and Phone.inc will POST a JSON payload to your endpoint in real time.

The webhook model

A webhook subscription tells Phone.inc where to send event notifications and which events to include.

Properties

Name
id
Type
string
Description
Unique public identifier for the webhook.
Name
name
Type
string
Description
A human-readable label for the webhook (e.g. Slack notifications, CRM sync).
Name
url
Type
string
Description
The HTTPS endpoint where events are delivered via POST.
Name
events
Type
array
Description
List of event types this webhook subscribes to. See Events for all available types.
Name
active
Type
boolean
Description
Whether the webhook is currently receiving events. Set to false to pause delivery without deleting the subscription.
Name
created_at
Type
timestamp
Description
ISO 8601 timestamp of when the webhook was created.
Name
updated_at
Type
timestamp
Description
ISO 8601 timestamp of the last update.

Events

Each event maps to a specific moment in a call's lifecycle or a voicemail being recorded.

Name
call.initiated
Description
A new inbound or outbound call has started. The call exists but hasn't been answered yet.
Name
call.outside_opening_hours
Description
An inbound call arrived outside the main number's configured opening hours.
Name
call.answered
Description
The call was answered by an employee. answered_at is now set on the call.
Name
call.ended
Description
The call has ended, regardless of outcome. Fires for every call that reaches the ended state — answered, missed, or rejected.
Name
call.lost
Description
The call ended without being answered and without going to voicemail. Somebody called, nobody picked up, no message was left.
Name
call.transcription_done
Description
The call recording has been transcribed. The transcription and transcription_segments fields are now populated on the call.
Name
voicemail.new
Description
A new voicemail was recorded and saved. The payload includes both the call and voicemail data.
Name
voicemail.transcription_done
Description
The voicemail recording has been transcribed. The payload's voicemail object now has its transcription field populated.

Payload structure

Every webhook delivery is a JSON POST with the following envelope:

Webhook payload

{
  "event": "call.answered",
  "timestamp": "2026-05-15T14:22:33Z",
  "data": {
    "id": "01JVWX...",
    "call_control_id": "v3:...",
    "from": "+14155551234",
    "to": "+14155559876",
    "direction": "inbound",
    "state": "answered",
    "started_at": "2026-05-15T14:22:00Z",
    "answered_at": "2026-05-15T14:22:33Z",
    "duration": null,
    "summary": null,
    "transcription": null,
    "transcription_segments": null,
    "main_number_id": "01JVWX...",
    "main_number_name": "Sales",
    "main_number_number": "+14155559876",
    "main_number_number_formatted": "(415) 555-9876",
    "employees": [{ "id": "01JVWX...", "name": "Jane Smith" }],
    "initiated_by": null
  }
}

The data object contains the full call model. For voicemail.new and voicemail.transcription_done events, the payload also includes a voicemail object nested inside data with the voicemail id, from, main_number_name, main_number_number, transcription, and created_at. The transcription is null on voicemail.new and populated on voicemail.transcription_done.

Your endpoint should return a 2xx status code to acknowledge receipt. Non-2xx responses trigger up to 5 retries with exponential backoff.

Webhook payloads are sent with Content-Type: application/json and a User-Agent: PhoneInc-Webhooks/1.0 header.

GET/v1/webhooks

List webhooks

Returns all webhook subscriptions for your company.

Request

GET

/v1/webhooks

curl https://app.phone.inc/api/v1/webhooks \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

[
  {
    "id": "01JVWX...",
    "name": "Slack notifications",
    "url": "https://example.com/webhooks",
    "events": ["call.initiated", "call.answered", "voicemail.new"],
    "active": true,
    "created_at": "2026-05-15T10:00:00Z",
    "updated_at": "2026-05-15T10:00:00Z"
  }
]

POST/v1/webhooks

Create a webhook

Registers a new webhook subscription.

Required attributes

Name
name
Type
string
Description
A human-readable label for the webhook.
Name
url
Type
string
Description
The HTTPS endpoint to receive events.
Name
events
Type
array
Description
One or more event types to subscribe to. See Events.

Request

POST

/v1/webhooks

curl -X POST https://app.phone.inc/api/v1/webhooks \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack notifications",
    "url": "https://example.com/webhooks",
    "events": ["call.initiated", "call.answered"]
  }'

Response

{
  "id": "01JVWX...",
  "name": "Slack notifications",
  "url": "https://example.com/webhooks",
  "events": ["call.initiated", "call.answered"],
  "active": true,
  "created_at": "2026-05-15T10:00:00Z",
  "updated_at": "2026-05-15T10:00:00Z"
}

PATCH/v1/webhooks/:id

Update a webhook

Updates an existing webhook. You can change the URL, events, or toggle it on/off.

Optional attributes

Name
name
Type
string
Description
New label for the webhook.
Name
url
Type
string
Description
New endpoint URL.
Name
events
Type
array
Description
Replace the subscribed events list.
Name
active
Type
boolean
Description
Set to false to pause delivery, true to resume.

Request

PATCH

/v1/webhooks/:id

curl -X PATCH https://app.phone.inc/api/v1/webhooks/01JVWX... \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

Response

{
  "id": "01JVWX...",
  "name": "Slack notifications",
  "url": "https://example.com/webhooks",
  "events": ["call.initiated", "call.answered"],
  "active": false,
  "created_at": "2026-05-15T10:00:00Z",
  "updated_at": "2026-05-15T14:30:00Z"
}

DELETE/v1/webhooks/:id

Delete a webhook

Permanently removes a webhook subscription. Events will stop being delivered immediately.

Request

DELETE

/v1/webhooks/:id

curl -X DELETE https://app.phone.inc/api/v1/webhooks/01JVWX... \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Returns 204 No Content on success.