> 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.

# Fax Events

POST 

Receive `FAX.STATUS` lifecycle updates, including cancellation, and `FAX.RECEIVED` notifications for completed inbound faxes. Fax and these events are available only in Pinnacle's HIPAA cell.

Delivery is at least once. Verify `PINNACLE-SIGNING-SECRET`, return HTTP 200 to acknowledge receipt, and deduplicate retries using the stable event `id`. Do not assume webhook delivery order; fetch `GET /fax/{id}` when you need the latest state. Fetch the same endpoint for a one-hour signed document URL; webhook payloads never contain document URLs.

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

## Request

### Headers

- `PINNACLE-SIGNING-SECRET` (string, required) — Secret for verifying the authenticity of the request. It starts with `pss-` and is unique to the webhook.

### Payload

- `id` (string, required) — Stable event ID. Deduplicate retries using this value.
- `type` (enum, required)
  - Allowed values: `FAX.STATUS`, `FAX.RECEIVED`
- `fax` (Fax, required)

## Types

### Fax

- `id` (string, required)
- `direction` (enum, required) — `OUTBOUND` for faxes sent by your team or `INBOUND` for faxes received by your team.
  - Allowed values: `INBOUND`, `OUTBOUND`
- `from` (string, required) — Sender number in E.164 format.
- `to` (string, required) — Recipient number in E.164 format.
- `status` (enum, required) — Current state of the fax: - `PREPARING`: Pinnacle is downloading, validating, converting, splitting, or archiving the document. - `SUBMITTING`: The fax is waiting for transmission to start. - `SUBMISSION_UNKNOWN`: Transmission may have started, but Pinnacle cannot confirm it. The fax is not retried automatically. - `QUEUED`: The outbound fax is queued for transmission. - `PROCESSING`: The outbound document is being processed. - `SENDING`: The outbound fax is being transmitted. - `RECEIVING`: An inbound fax is in progress. - `DELIVERED`: Every outbound part was delivered. - `RECEIVED`: The inbound fax was received and archived. - `FAILED`: Preparation, submission, or delivery failed. `partialContent` indicates whether any pages were transmitted. - `CANCELLED`: The outbound fax was cancelled before transmission started.
  - Allowed values: `PREPARING`, `SUBMITTING`, `SUBMISSION_UNKNOWN`, `QUEUED`, `PROCESSING`, `SENDING`, `RECEIVING`, `DELIVERED`, `RECEIVED`, `FAILED`, `CANCELLED`
- `pages` (integer, required) — Transmitted page count across the fax. This can be zero before transmission and can include only transmitted pages after a partial failure. Outbound documents can contain at most 3,500 pages.
- `durationSeconds` (double, required) — Total transmission duration in seconds.
- `partialContent` (boolean, required) — Whether only part of the document was delivered, including when an earlier part succeeded before a later part failed.
- `failureReason` (enum, required) — Stable failure category, or null when no failure is recorded: - `MEDIA_PREPARATION_FAILED`: The source was unavailable, invalid, unsupported, over a limit, or could not be rendered. - `MEDIA_PREPARATION_INTERRUPTED`: Preparation could not be completed after retries. - `INSUFFICIENT_CREDITS`: The team's available credits could not cover the prepared page count. - `SUBMISSION_UNCONFIRMED`: Transmission may have started, so Pinnacle will not retry automatically. - `SUBMISSION_REJECTED`: Transmission could not start. - `DELIVERY_FAILED`: Delivery failed or a transmitted part did not match the expected page count.
  - Allowed values: `MEDIA_PREPARATION_FAILED`, `MEDIA_PREPARATION_INTERRUPTED`, `INSUFFICIENT_CREDITS`, `SUBMISSION_UNCONFIRMED`, `SUBMISSION_REJECTED`, `DELIVERY_FAILED`
- `cost` (double, required) — Settled fax cost in USD, calculated at $0.025 per final transmitted page. Quality does not change the rate.
- `reservedCost` (double, required) — Credit reserved after document preparation for an unsettled outbound fax, in USD. This equals $0.025 multiplied by the prepared page count, regardless of quality, and is zero while status is `PREPARING`.
- `billingStatus` (enum, required) — `PENDING` while a reservation or uncertain submission remains open; `SETTLED` after final charging, refund, or cancellation.
  - Allowed values: `PENDING`, `SETTLED`
- `hasMedia` (boolean, required) — Whether Pinnacle has archived the fax document.
- `createdAt` (string, required)
- `updatedAt` (string, required)