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	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	All retryable attempts 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.

The envelope

Every event carries the same outer shape:

{
  "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

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 and deduplicate on webhook-id.

Next

• Per-event pages: fax.queued, fax.sending, fax.delivered, fax.failed, balance.low, balance.topup
• Verify webhook signatures
• Delivery and retries