Sign in
Webhooks

Phone Incoming Call

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}.
postWebhook/phone-call

Payload

idstring uuid required
origin'dedicated_number' | 'shared_imessage_number' | 'dedicated_imessage_number'
local_phone_numberstring nullable
remote_phone_numberstring required
direction'inbound' required
status'initiated' | 'ringing' | 'answered' | 'completed' | 'failed' | 'canceled' required
client_websocket_urlstring nullable required
use_inkbox_ttsboolean nullable required
use_inkbox_sttboolean nullable required
hangup_reason'local' | 'remote' | 'max_duration' | 'voicemail' | 'rejected' | 'failed'
started_atstring date-time nullable required
ended_atstring date-time nullable required
created_atstring date-time required
updated_atstring date-time required

Response

Successful Response

action'answer' | 'reject' required

Whether to answer or reject the call

client_websocket_urlstring nullable

WebSocket URL (wss://) for audio bridging. Falls back to the phone number's client_websocket_url.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.