---
title: "Phone Incoming Call"
method: POST
path: "/phone-call"
tags: ["Webhooks"]
---

# Phone Incoming Call

`POST /phone-call` (webhook)

Fired when an incoming call arrives on a phone number whose `incoming_call_action` is `webhook`. The request body is a flat call payload, not an `{event_type, timestamp, data}` envelope. Your endpoint must return a JSON body with `action` (`answer` or `reject`) within 10 seconds. Non-200 responses, invalid bodies, or timeouts are treated as `ignore`.

If your organization has a signing key, every webhook includes three headers:
- `X-Inkbox-Request-ID` — UUID for deduplication.
- `X-Inkbox-Timestamp` — Unix timestamp in seconds.
- `X-Inkbox-Signature` — `sha256={HMAC-SHA256 hex digest}` over `{request_id}.{timestamp}.{raw_body}`.

## Payload

- PhoneCallWebhookPayload
  - `id` string, uuid, required
  - `origin` 'dedicated_number' | 'shared_imessage_number' | 'dedicated_imessage_number'
  - `local_phone_number` string, nullable
  - `remote_phone_number` string, required
  - `direction` 'inbound', required
  - `status` 'initiated' | 'ringing' | 'answered' | 'completed' | 'failed' | 'canceled', required
  - `client_websocket_url` string, nullable, required
  - `use_inkbox_tts` boolean, nullable, required
  - `use_inkbox_stt` boolean, nullable, required
  - `hangup_reason` 'local' | 'remote' | 'max_duration' | 'voicemail' | 'rejected' | 'failed'
  - `started_at` string, date-time, nullable, required
  - `ended_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `rate_limit` RateLimitInfo
    - `calls_used` integer, required
    - `calls_remaining` integer, required
    - `calls_limit` integer, required
    - `minutes_used` number, required
    - `minutes_remaining` number, required
    - `minutes_limit` integer, required
  - `contacts` WebhookContact[]
    - `id` string, uuid, required
    - `name` string, nullable, required
    - `memories` string[]
  - `agent_identities` WebhookAgentIdentity[]
    - `id` string, uuid, required
    - `agent_handle` string, required
    - `display_name` string, nullable

## Acknowledgement `200`

Successful Response

- IncomingCallWebhookResponse
  - `action` 'answer' | 'reject', required — Whether to answer or reject the call
  - `client_websocket_url` string, nullable — WebSocket URL (wss://) for audio bridging. Falls back to the phone number's client_websocket_url.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) · [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inkbox/inkbox-api/revisions/31f357e7e6f8/schema)