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.

Webhooks push fax status updates to your server as they happen, so you don’t need to poll.

​
Setup

Configure your webhook URL and event subscriptions via PUT /account/settings: 
curl -X PUT https://api.mintfax.com/v1/account/settings \
  -H "Authorization: Bearer fx_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://acme.com/webhooks/mintfax",
    "webhook_events": ["fax.delivered", "fax.failed"]
  }'

​
Event Types

EventFires when
fax.submittedFax accepted and queued for processing
fax.deliveredFax successfully delivered
fax.failedFax permanently failed (all retries exhausted)
balance.lowBalance drops below configured threshold
balance.topupCredits added to account

​
Payload Format

Every webhook payload includes a unique event_id for deduplication: 
{
  "event_id": "evt_abc123def456",
  "event": "fax.delivered",
  "timestamp": "2026-01-15T10:30:05Z",
  "data": {
    "id": "9c1a2b3d-4e5f-6789-abcd-ef0123456789",
    "status": "delivered",
    "to": "+12125551234",
    "pages": 3,
    "completed_at": "2026-01-15T10:30:05Z"
  }
}

​
Signature Verification

Every webhook request is signed with HMAC-SHA256 so you can verify it came from mintfax. See Webhook signing and verification for implementation steps, multi-language code samples, and key rotation handling.

​
Per-Fax Webhook Override

Override the account-level webhook URL for a specific fax by passing webhook_url in the send request: 
curl -X POST https://api.mintfax.com/v1/fax \
  -H "Authorization: Bearer fx_test_abc123..." \
  -F "to=+12125551234" \
  -F "file=@document.pdf" \
  -F "webhook_url=https://acme.com/webhooks/urgent-fax"

​
Delivery Behavior

  • Retries: failed deliveries are retried with exponential backoff
  • Ordering: events may arrive out of order. Use timestamp and fax status to determine the latest state.
  • Duplicates: your endpoint may receive the same event more than once. Use event_id for deduplication.
  • Timeouts: your endpoint should respond within 5 seconds. Slow responses trigger retries.