Event types

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.

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

Get Started

Event types

The catalog

The envelope

Branching on the type field

Exactly-once vs may-fire-multiple

Next

​The catalog

​The envelope

​Branching on the type field

​Exactly-once vs may-fire-multiple

​Next

The catalog

The envelope

Branching on the type field

Exactly-once vs may-fire-multiple

Next