---
title: "Call Lifecycle Event"
method: POST
path: "/phone-call-lifecycle"
tags: ["Webhooks"]
---

# Call Lifecycle Event

`POST /phone-call-lifecycle` (webhook)

Fired for post-call lifecycle events on an agent identity with an active call-lifecycle subscription. Covers `call.ended`, delivered once after a connected call terminates. The request body uses the standard `{event_type, timestamp, data}` envelope with `data.call`, `data.contacts`, `data.agent_identities`, and `data.transcript_url`. `data.transcript` (an abridged, middle-cut copy) is present only when the call has a persisted transcript; `data.transcript_url` is always present and authoritative. Unlike the synchronous `phone.incoming_call` callback, this is fire-and-forget and replayable: the response status is logged but does not affect call processing.

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

- PhoneCallEndedWebhookPayload
  - `id` string, required — Stable per-event id (evt_...); idempotency key, stable across replays.
  - `event_type` 'call.ended', required
  - `timestamp` string, date-time, required — ISO 8601 timestamp of when the event occurred.
  - `data` PhoneCallEndedWebhookData, required
    - `call` WebhookPhoneCall, required
      - `id` string, uuid, required
      - `origin` 'dedicated_number' | 'shared_imessage_number' | 'dedicated_imessage_number'
      - `local_phone_number` string, nullable
      - `remote_phone_number` string, required
      - `direction` 'outbound' | 'inbound', required
      - `status` 'initiated' | 'ringing' | 'answered' | 'completed' | 'failed' | 'canceled', required
      - `mode` 'client_websocket' | 'hosted_agent'
      - `hosted_agent_authority_mode` 'contact_scoped' | 'yolo'
      - `voicemail_detection` 'enabled' | 'disabled'
      - `reason` string, nullable
      - `forwardings` PhoneCallForwardingResponse[]
        - `id` string, uuid, required
        - `trigger` 'incoming_action', required
        - `status` 'requested' | 'dialing' | 'forwarded' | 'failed', required
        - `target_type` 'phone' | 'sip', required
        - `target` string, required
        - `requested_at` string, date-time, required
        - `dialing_at` string, date-time, nullable
        - `forwarded_at` string, date-time, nullable
        - `ended_at` string, date-time, nullable
        - `failure_code` string, nullable
      - `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
      - `duration_seconds` integer, nullable
    - `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
    - `transcript` WebhookCallTranscript
      - `entries` WebhookTranscriptEntry[]
        - `party` string, nullable
        - `text` string, nullable
        - `ts_ms` integer, nullable
        - `truncated` boolean, nullable
        - `marker` 'abridged', nullable
        - `omitted_turns` integer, nullable
        - `omitted_ms` integer, nullable
      - `abridged` boolean
      - `url` string, required
    - `transcript_url` string, required
    - `outcome` 'completed' | 'no_answer' | 'declined' | 'failed'
    - `post_call_action_items` WebhookPostCallAction[]
      - `id` string, uuid, required
      - `seq` integer, required
      - `action` string, required
      - `details` string, nullable
      - `status` 'open' | 'canceled'

## Acknowledgement `200`

Successful Response

- unknown

## 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)