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 for full payload schemas.

The envelope

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

{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "type": "fax.delivered",
  "created": 1747173600,
  "data": {
    "object": {
      "id": "fax_8aZqRm4yT3vK7pNxJ2bH9c",
      "status": "delivered",
      "to": "[phone]"
    }
  }
}

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. 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.
5. Inspect attempts when something looks off. The dashboard surfaces every delivery attempt with status, response, and signature headers. See Inspect delivery 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
• Delivery and retries
• Inspect delivery attempts
• Event types