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

# Event types

> Every event mintfax can send, when each fires, and the payload structure shared across the catalog.

Each webhook delivery carries a typed event. The list below is the complete catalog. Pages for each event document the firing rules and the payload shape.

## The catalog

| Event                                             | When it fires                                                           |
| ------------------------------------------------- | ----------------------------------------------------------------------- |
| [`fax.queued`](/docs/webhooks/events/fax-queued)       | Fax accepted, hold placed, queued for delivery.                         |
| [`fax.sending`](/docs/webhooks/events/fax-sending)     | Delivery attempt against the destination has started.                   |
| [`fax.delivered`](/docs/webhooks/events/fax-delivered) | Fax delivered successfully. Hold captured.                              |
| [`fax.failed`](/docs/webhooks/events/fax-failed)       | All retryable attempts exhausted or a terminal error code was returned. |
| [`balance.low`](/docs/webhooks/events/balance-low)     | Available balance crossed the configured low-balance threshold.         |
| [`balance.topup`](/docs/webhooks/events/balance-topup) | Funds added to the environment.                                         |

## The envelope

Every event carries the same outer shape:

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

| Field         | Meaning                                                                      |
| ------------- | ---------------------------------------------------------------------------- |
| `id`          | Event identifier. Stable across retry attempts of the same event.            |
| `type`        | The event type, exactly one of the values above.                             |
| `created`     | Unix epoch seconds when the event was generated.                             |
| `data.object` | The resource snapshot at the moment the event fired. Schema varies per type. |

`data.object` for `fax.*` events is the fax resource (same fields as `GET /faxes/{id}`) plus per-attempt detail. For `balance.*` events, it is a balance snapshot.

## Branching on the type field

```javascript theme={null}
switch (event.type) {
  case "fax.queued":
    // Hold confirmed, fax in line.
    break;
  case "fax.sending":
    // A delivery attempt has begun.
    break;
  case "fax.delivered":
    // Terminal success.
    break;
  case "fax.failed":
    // Terminal failure. event.data.object.error_code is set.
    break;
  case "balance.low":
  case "balance.topup":
    // Account balance change.
    break;
}
```

The list of event types is the contract. New event types are introduced under new names, never by changing what an existing type carries. Subscribers receive only the types they have subscribed to.

## Exactly-once vs may-fire-multiple

| Event           | Cardinality per fax / event                                     |
| --------------- | --------------------------------------------------------------- |
| `fax.queued`    | Exactly once.                                                   |
| `fax.sending`   | One per delivery attempt against the destination.               |
| `fax.delivered` | Exactly once. Mutually exclusive with `fax.failed`.             |
| `fax.failed`    | Exactly once. Mutually exclusive with `fax.delivered`.          |
| `balance.low`   | May fire repeatedly if balance oscillates around the threshold. |
| `balance.topup` | One per credit addition.                                        |

Webhook *delivery* of any event may retry on the wire if your endpoint did not 2xx the first time. See [Delivery and retries](/docs/webhooks/delivery-and-retries) and deduplicate on `webhook-id`.

## Next

* Per-event pages: [`fax.queued`](/docs/webhooks/events/fax-queued), [`fax.sending`](/docs/webhooks/events/fax-sending), [`fax.delivered`](/docs/webhooks/events/fax-delivered), [`fax.failed`](/docs/webhooks/events/fax-failed), [`balance.low`](/docs/webhooks/events/balance-low), [`balance.topup`](/docs/webhooks/events/balance-topup)
* [Verify webhook signatures](/docs/webhooks/verify-requests)
* [Delivery and retries](/docs/webhooks/delivery-and-retries)