Webhooks

Signed JSON POSTed when a fax you sent reaches delivered or failed.

Register

Add an endpoint URL in Account. The signing secret is shown once at create time — copy it immediately. Listed endpoints show only a truncated prefix.

Events

• fax.delivered
• fax.failed

Request

We POST JSON with headers:

• content-type: application/json
• user-agent: agent-fax-webhooks/1.0
• x-agent-fax-event — event type
• x-agent-fax-signature — t=<unix>,v1=<hex>
• x-agent-fax-delivery-id — stable delivery id

{
  "id": "evt_<jobId>_<event>",
  "type": "fax.delivered",
  "created_at": 1710000000,
  "data": {
    "fax": {
      "id": "fx_...",
      "status": "delivered",
      "to": "+15125550123",
      "pages": 1,
      "amount_cents": 124,
      "failure_code": null,
      "failure_reason": null,
      "completed_at": 1710000000
    }
  }
}

Verify the signature

Compute HMAC-SHA256 over the UTF-8 string ${timestamp}.${rawBody} using your endpoint secret. The header value is t=<timestamp>,v1=<hex digest>. Compare v1 in constant time. Reject if the timestamp is too old for your replay window.

Respond with 2xx to acknowledge. Non-2xx responses are retried with backoff. 410 Gone stops retries for that endpoint.

Next: Limits · Open Account