> ## Documentation Index
> Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive fax events with webhooks

> Subscribe to fax lifecycle and balance events. Real-time delivery, signed payloads, and replayable history.

mintfax sends a signed HTTP POST to your URL every time something noteworthy happens to a fax or to your account balance. Subscribe once, handle events as they arrive.

## What you can subscribe to

| Event           | When it fires                                                               |
| --------------- | --------------------------------------------------------------------------- |
| `fax.queued`    | Fax accepted, hold placed, queued for delivery.                             |
| `fax.sending`   | Delivery attempt against the destination has started.                       |
| `fax.delivered` | Fax delivered successfully. Hold captured.                                  |
| `fax.failed`    | Every retryable attempt is exhausted or a terminal error code was returned. |
| `balance.low`   | Available balance crossed the configured low-balance threshold.             |
| `balance.topup` | Funds added to the environment (manual or auto-top-up).                     |

See [Event types](/docs/webhooks/events/overview) for full payload schemas.

## The envelope

Every delivery shares the same outer envelope. The `data.object` shape varies per event.

```json theme={null}
{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "type": "fax.delivered",
  "created": 1747173600,
  "data": {
    "object": {
      "id": "fax_8aZqRm4yT3vK7pNxJ2bH9c",
      "status": "delivered",
      "to": "+12125551234"
    }
  }
}
```

`id` is the event identifier (`evt_`-prefixed). It is stable across retry attempts, which is what makes deduplication on `id` safe.

## Get started

1. **Register a webhook endpoint** in the dashboard or via `POST /webhooks`. You will receive a `whsec_`-prefixed signing secret. It is shown once.
2. **Subscribe to events.** Each endpoint can subscribe to all events or to a specific list.
3. **Verify every request.** See [Verify webhook signatures](/docs/webhooks/verify-requests). mintfax follows the Standard Webhooks specification, so you can use a reference library in your language without writing custom verification code.
4. **Acknowledge with a 2xx response.** Any 2xx status code is treated as successful delivery. Non-2xx responses or timeouts schedule a retry. See [Delivery and retries](/docs/webhooks/delivery-and-retries).
5. **Inspect attempts when something looks off.** The dashboard shows every delivery attempt with status, response, and signature headers. See [Inspect delivery attempts](/docs/webhooks/inspect-attempts).

## Headers on every delivery

| Header              | Value                                                   |
| ------------------- | ------------------------------------------------------- |
| `webhook-id`        | Event identifier. Stable across retry attempts.         |
| `webhook-timestamp` | Unix epoch seconds. Re-stamped per delivery attempt.    |
| `webhook-signature` | One or more space-separated `v1,<base64-hmac>` tokens.  |
| `Content-Type`      | `application/json`                                      |
| `User-Agent`        | `mintfax-webhooks/1.0`                                  |
| `Request-Id`        | Correlates with the `Request-Id` returned by API calls. |

## Next

* [Verify webhook signatures](/docs/webhooks/verify-requests)
* [Delivery and retries](/docs/webhooks/delivery-and-retries)
* [Inspect delivery attempts](/docs/webhooks/inspect-attempts)
* [Event types](/docs/webhooks/events/overview)