Skip to main content

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.

mintfax fires events when fax state changes or account conditions are met. Each event is delivered as an HTTP POST to your webhook endpoints. This page documents every event type, its payload shape, and how delivery works.

​
Event envelope

All events share the same top-level structure. The data object varies by event type. 
{
  "event": "fax.delivered",
  "event_id": "evt_01H7N9ZXKZB2C5MTPRDA3VFQE2",
  "timestamp": "2026-05-09T14:22:08Z",
  "data": { }
}
FieldTypeDescription
eventstringThe event type (e.g., fax.delivered)
event_idstringUnique ID (ULID) for this event. Use it for deduplication.
timestampstringISO 8601 UTC timestamp of when the event was created
dataobjectEvent-specific payload. Structure depends on event.

​
Fax events

​
fax.queued

Fires when a fax is accepted and placed in the processing queue. This is the first event in the fax lifecycle. 
{
  "event": "fax.queued",
  "event_id": "evt_01H7NA1WXYZ8VC2QPK5MTRDE3F",
  "timestamp": "2026-05-09T14:22:01Z",
  "data": {
    "id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA",
    "status": "queued",
    "to": "+12125551234",
    "created_at": "2026-05-09T14:22:01Z"
  }
}
A credit hold is placed when the fax is queued. If the hold fails due to insufficient balance, the fax is rejected with HTTP 402 and no event fires.

​
fax.sending

Fires when the fax is picked up from the queue and submitted to the carrier. 
{
  "event": "fax.sending",
  "event_id": "evt_01H7NA2WXYZ8VC2QPK5MTRDE3F",
  "timestamp": "2026-05-09T14:22:03Z",
  "data": {
    "id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA",
    "status": "sending",
    "to": "+12125551234",
    "pages": 3,
    "submitted_at": "2026-05-09T14:22:03Z"
  }
}
The pages field is populated once the document has been processed. It may be null in earlier events.

​
fax.delivered

Fires when the carrier confirms the fax was delivered. This is a terminal state. The credit hold is captured (balance charged). 
{
  "event": "fax.delivered",
  "event_id": "evt_01H7NA3WXYZ8VC2QPK5MTRDE3F",
  "timestamp": "2026-05-09T14:22:08Z",
  "data": {
    "id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA",
    "status": "delivered",
    "to": "+12125551234",
    "pages": 3,
    "completed_at": "2026-05-09T14:22:08Z"
  }
}

​
fax.failed

Fires when a fax permanently fails after all retries are exhausted. This is a terminal state. The credit hold is released (balance refunded). 
{
  "event": "fax.failed",
  "event_id": "evt_01H7NA4WXYZ8VC2QPK5MTRDE3F",
  "timestamp": "2026-05-09T14:25:30Z",
  "data": {
    "id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA",
    "status": "failed",
    "to": "+12125551234",
    "pages": 3,
    "error_code": "line_busy",
    "error_message": "Recipient line busy after all retry attempts",
    "completed_at": "2026-05-09T14:25:30Z"
  }
}
The error_code and error_message fields appear in fax.failed and fax.retry_scheduled events. See Errors for the full error catalog.

​
fax.retry_scheduled

Fires when a delivery attempt fails but retries remain. The fax stays in flight and will be retried automatically. 
{
  "event": "fax.retry_scheduled",
  "event_id": "evt_01H7NA5WXYZ8VC2QPK5MTRDE3F",
  "timestamp": "2026-05-09T14:23:15Z",
  "data": {
    "id": "fax_01H7N9WXYZ8VC2QPK5MTRDE3FA",
    "status": "retry_scheduled",
    "to": "+12125551234",
    "pages": 3,
    "retries_remaining": 2,
    "error_code": "line_busy",
    "error_message": "Recipient line busy"
  }
}
If you receive fax.retry_scheduled, wait for either fax.delivered or fax.failed before taking action. The credit hold remains active during retries.

​
Balance events

​
balance.low

Fires when a credit transaction brings the workspace’s available balance below 20% of its last top-up amount. Fires at most once per top-up cycle - the threshold resets when credits are added (via purchase or auto top-up). 
{
  "event": "balance.low",
  "event_id": "evt_01H7NA6WXYZ8VC2QPK5MTRDE3F",
  "timestamp": "2026-05-09T15:01:00Z",
  "data": {
    "available_balance": 12,
    "currency": "credits",
    "threshold_pct": 20
  }
}
Use this event to trigger top-up logic or alert an operator. If auto top-up is enabled on the workspace, mintfax handles replenishment automatically, and you will receive a balance.topup event when it completes.

​
balance.topup

Fires when credits are added to the workspace, whether through a manual purchase or auto top-up. 
{
  "event": "balance.topup",
  "event_id": "evt_01H7NA7WXYZ8VC2QPK5MTRDE3F",
  "timestamp": "2026-05-09T15:01:05Z",
  "data": {
    "new_balance": 512,
    "amount_added": 500,
    "currency": "credits",
    "source": "auto_topup"
  }
}
The source field is either "manual" (developer-initiated purchase) or "auto_topup".

​
Delivery behavior

​
Ordering

Events may arrive out of order. A fax.delivered event could reach your endpoint before fax.sending if network conditions vary. Use the timestamp field and the fax status to determine the latest state. Do not assume arrival order equals chronological order.

​
Deduplication

Your endpoint may receive the same event more than once. Every event carries a unique event_id. Store processed event IDs and skip duplicates.

​
Retries

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, mintfax retries delivery with exponential backoff:
AttemptDelay after failure
110 seconds
260 seconds
3300 seconds
After 3 failed retries, the event is dropped. mintfax does not retry further. You can retrieve the current state of any fax via GET /fax/{id} as a fallback.

​
Signature

All webhook payloads are signed with HMAC-SHA256 using your endpoint’s signing secret. The signature is sent in the X-Mintfax-Signature header. See Webhooks for verification examples.

​
See also

  • Webhooks - endpoint setup, per-fax overrides, signature verification
  • Errors - error codes referenced in fax.failed and fax.retry_scheduled events
  • Sandbox - test event delivery with magic numbers
Last updated: 2026-05-09