> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://docs.pinnacle.sh/v-2/llms.txt
> - v1: https://docs.pinnacle.sh/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pinnacle.sh/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server.

# Call Events

POST 

Receive `CALL.STATUS` events as voice calls move through their lifecycle.

Subscribe by attaching a webhook to a voice-enabled phone number. `CALL.STATUS`
is only supported for phone number senders, not RCS agent senders.

**Before trusting the payload, verify the `PINNACLE-SIGNING-SECRET` header matches the signing secret of the webhook this event was delivered to.** Respond with a `200` to acknowledge receipt — any non-2xx response causes Pinnacle to retry with exponential backoff.


Reference: https://docs.pinnacle.sh/webhooks/call-events

## Request

### Headers

- `PINNACLE-SIGNING-SECRET` (string, required) — Secret for verifying the authenticity of the request. Starts with `pss-` and is unique for each webhook. Find it at [webhooks](https://app.pinnacle.sh/dashboard/development/webhooks).

### Payload

- `type` (enum, required)
  - Allowed values: `CALL.STATUS`
- `sender` (string, required) — Team-owned phone number that matched the webhook subscription. For inbound calls this is the `call.to` number; for outbound calls this is the `call.from` number.
- `call` (CallStatusEventCall, required)

## Types

### CallStatusEventCall

- `id` (string, required) — Pinnacle call ID.
- `from` (string, required) — Caller phone number in E.164 format.
- `to` (string, required) — Callee phone number in E.164 format.
- `direction` (enum, required) — Direction of the call relative to your Pinnacle team. - `INBOUND`: The call originated from an external caller and was received by one of your Pinnacle voice-enabled phone numbers. - `OUTBOUND`: The call was created from Pinnacle and dialed out from one of your voice-enabled phone numbers.
  - Allowed values: `INBOUND`, `OUTBOUND`
- `status` (enum, required) — Current voice call lifecycle state. This uses the same values as the Call `state` field. - `INITIATED`: Pinnacle accepted the call request and is setting up the call with the voice provider. - `RINGING`: The call is ringing and has not been answered yet. - `ANSWERED`: The call has been answered and is active. - `BRIDGED`: The call is connected to another call leg, such as after a transfer or bridge command. - `ENDED`: The call ended normally. - `FAILED`: The call could not be established or could not continue because of a provider or system failure. - `NO_ANSWER`: The call rang until timeout without being answered. - `BUSY`: The destination was busy. - `CANCELED`: The call was canceled before normal completion.
  - Allowed values: `INITIATED`, `RINGING`, `ANSWERED`, `BRIDGED`, `ENDED`, `FAILED`, `NO_ANSWER`, `BUSY`, `CANCELED`