Webhook

Definition

A webhook delivers a POST request to your server when a fax event happens. Use it instead of polling fax or outbox endpoints. The current API is POST /v3/webhooks. The older POST /v3/hooks API still works and is documented as legacy.

Webhooks must be enabled for your account. Open Settings → Integrations and enable webhooks before you call /v3/webhooks. Until then the API returns 404 (application not found, enable webhooks in Fax.Plus integrations settings). The account also needs the webhooks feature; otherwise the API returns 403.

Events

Use underscore names only. Dotted aliases are not accepted.

Event	When it fires
`fax_sent`	Outbound fax finished (success or failure — check `data.status`)
`fax_received`	Inbound fax finished
`fax_page_received`	One inbound page arrived. Requires fax streaming (on request)

One endpoint can subscribe to several events via filter_types.

Setting up webhooks

Enable webhooks in Integrations. After you create an endpoint, copy its signing secret from that panel (see Verify signatures).
Expose an HTTPS URL that accepts POST and returns 200 quickly.
Create the endpoint with the API:

curl -X POST https://restapi.fax.plus/v3/webhooks \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/fax-webhooks",
    "filter_types": ["fax_sent", "fax_received"]
  }'

url and filter_types are required. filter_types must contain at least one event. A create that only sends url is 400. Create returns 201 with an empty body. List endpoints afterward to read the ep_… id.

See Create a webhook endpoint for the full request.

Number filters (`channels`)

Optional channels is a list of E.164 numbers (+12135550123). The endpoint fires only when the fax from or to matches one of them. You may include numbers you do not own — including the remote party. Values with a leading + are normalized to E.164 (+1 571 690 8695 → +15716908695). A number without + is rejected with 400 (Invalid number) — the request never creates or updates the endpoint.

Omit channels (or send null on create) to receive every matching event.
On PATCH /v3/webhooks/{endpoint_id}, send "channels": null to clear filters. Omitted fields stay unchanged.

Handling webhook notifications

Method: HTTP POST, JSON body.
Shape: { "hook": { … }, "data": { … } } — same shape as the legacy API.
hook.target: always "" on /v3/webhooks deliveries. One event can go to several endpoints, so the payload cannot carry a single destination URL. Use your own endpoint URL, not this field. Legacy /v3/hooks still fills target with the configured URL.

Verify signatures

/v3/webhooks deliveries are signed with HMAC-SHA256. This is a shared signing secret, not a TLS or X.509 certificate. The REST API never returns the secret.

Where to get the secret

Open Settings → Integrations.
In the Webhooks section, click Manage. A panel opens.
Create the webhook if it does not exist yet, then click it.
Open Advanced and scroll to the bottom.
Expand Signing Secret and use the eye icon to reveal it. Each endpoint has its own secret; rotating it invalidates the previous value.

Webhook Advanced settings with Signing Secret at the bottom

Treat it like a password. Do not commit it or expose it in client-side code. The REST API never returns this secret.

Headers

Every current-API POST includes:

HTTP header	Meaning
`webhook-id`	Unique id for this delivery. Retries and replays of the same delivery reuse this value.
`webhook-timestamp`	Unix timestamp (seconds) when the delivery was signed.
`webhook-signature`	One or more signatures, space-separated, each `v1,<base64>`.

How to verify

Read the raw request body as bytes. Do not parse and re-serialize JSON first — whitespace changes break the signature.
Drop the whsec_ prefix from the secret and base64-decode the rest. That is the HMAC key.
Build the signed string exactly as: {webhook-id}.{webhook-timestamp}.{raw body} Example: msg_abc.1710000000.{"hook":…}
Compute HMAC-SHA256(key, signed_string) and base64-encode the digest.
Compare that value to each v1, signature in webhook-signature using a constant-time compare. Accept if any matches.
Reject the request if webhook-timestamp is more than 5 minutes off your clock (replay protection).

Python
JavaScript

import base64
import hashlib
import hmac
import time

def verify_webhook(secret: str, msg_id: str, timestamp: str, body: bytes, signatures: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(
        hmac.new(key, f"{msg_id}.{timestamp}.".encode() + body, hashlib.sha256).digest()
    ).decode()
    return any(
        hmac.compare_digest(expected, part.split(",", 1)[-1])
        for part in signatures.split()
        if part.startswith("v1,")
    )

const crypto = require("crypto");

function verifyWebhook(secret, msgId, timestamp, body, signatures) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return false;
  }
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = crypto
    .createHmac("sha256", key)
    .update(`${msgId}.${timestamp}.`)
    .update(body)
    .digest("base64");
  return signatures.split(" ").some((part) => {
    if (!part.startsWith("v1,")) return false;
    const sig = Buffer.from(part.slice(3));
    const exp = Buffer.from(expected);
    return sig.length === exp.length && crypto.timingSafeEqual(exp, sig);
  });
}

Optional: allowlist source IPs

To allowlist source IPs, see the current list in the Fax.Plus webhooks help article.

Payload

fax_sent

Fired when an outbound fax session finishes. Check data.status — it is not success-only.

fax_sent payload

{
    "hook": {
        "id": "66df09cf1d6d0b295c363956",
        "event": "fax_sent",
        "event_time": "2024-09-09 10:44:39",
        "target": ""
    },
    "data": {
        "id": "66df09cf1d6d0b295c363956",
        "uid": "490ae330dbc749f0b6561dafa300f2fb",
        "pages": 1,
        "from": "+1 334-304-xxxx",
        "to": "+1 334-304-xxxx",
        "start_time": "2024-09-09 10:44:39",
        "file": "1d0b618e4fb54957878eed0ecc64ae5e.tiff",
        "file_name": "fax-to-1334304xxxx",
        "status": "success",
        "cost": 1
    }
}

If hook.id is not equal to data.id, the fax is being retried. If they match, this is the first attempt.

Payload schema

Name	Type	Required	Description
hook	object	Yes	Hook and event description
id	`string`	Yes	Fax ID
event	`string`	Yes	Event type
event_time	`string`	Yes	Time of the event. Format: YYYY-MM-DD HH:mm:ss
target	`string`	Yes	Empty string on `/v3/webhooks`. Legacy `/v3/hooks` sends the configured URL
data	object	Yes	Callback data, depends on the event type
id	`string`	Yes	Fax session ID. This ID might differ from the one returned by listFaxes
uid	`string`	Yes	Sender user ID
pages	`number`	Yes	Number of pages in the fax
from	`string`	Yes	Sender number. Might be a user ID for faxes sent from free accounts
to	`string`	Yes	Fax destination number. Might be a user ID for faxes sent from free accounts
start_time	`string`	Yes	Time at which faxing session started. Format: YYYY-MM-DD HH:mm:ss
file	`string`	Yes	File ID
file_name	`string`	Yes	Human-readable file name
cost	`number`	Yes	Fax cost (in pages)
status	`FaxStatus`	Yes	Fax status

fax_received

Fired when an inbound fax session finishes.

fax_received payload

{
    "hook": {
        "id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
        "event": "fax_received",
        "event_time": "2024-09-09 12:44:39",
        "target": ""
    },
    "data": {
        "id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
        "uid": "490ae330dbc749f0b6561dafa300f2fb",
        "pages": 1,
        "from": "+1 334-304-xxxx",
        "to": "+1 334-304-xxxx",
        "start_time": "2024-09-09 12:44:39",
        "file": "27ade44579274f01b55e552cd361990e.tiff",
        "file_name": "fax-from-1334304xxxx",
        "status": "success",
        "cost": 1
    }
}

Payload schema

Same schema as fax_sent.

fax_page_received

The fax_page_received event is only available if your account has fax streaming enabled. This feature is available on request — contact us to discuss enabling it for your account.

Fired once per received page so you can process pages before the fax completes.

fax_page_received payload

{
    "hook": {
        "id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
        "event": "fax_page_received",
        "event_time": "2024-09-09 12:44:39",
        "target": ""
    },
    "data": {
        "id": "9b0cfcad-5bf8-41ff-94f7-eb5b1b85a0bf",
        "page": 1,
        "from": "+1 334-304-xxxx",
        "to": "+1 334-304-xxxx"
    }
}

Payload schema

Name	Type	Required	Description
hook	object	Yes	Hook and event description
id	`string`	Yes	Fax session ID
event	`string`	Yes	Event type
event_time	`string`	Yes	Time of the event. Format: YYYY-MM-DD HH:mm:ss
target	`string`	Yes	Empty string on `/v3/webhooks`. Legacy `/v3/hooks` sends the configured URL
data	object	Yes	Callback data for the page received event
id	`string`	Yes	Fax session ID
page	`number`	Yes	Page number that was received (starting from 1)
from	`string`	Yes	Sender number. Might be a user ID for faxes sent from free accounts
to	`string`	Yes	Fax destination number. Might be a user ID for faxes sent from free accounts

Handling the notification

Verify the HMAC.
Parse hook.event and data.
Apply your business logic. See Idempotency.
Return 200 quickly. Long work belongs in a queue. Non-2xx responses are retried.

Idempotency

The same delivery can hit your URL more than once: automatic retries after a non-2xx, or a manual replay from the Integrations panel. The webhook-id HTTP header identifies that delivery. It is not a field in the JSON body. Retries and replays keep the same header value. A new fax event gets a new one. hook.id and data.id in the payload identify the fax, not the delivery. Do not use them as the only dedup key. Read webhook-id from the request headers and store each value you have already processed (cache or database, keep it for at least a few days). If it is already stored, skip the work and still return 200 so retries stop. If you return an error after you already applied the update, the next retry will send the same webhook-id header again.

API reference

Action	Endpoint
List	`GET /v3/webhooks`
Create	`POST /v3/webhooks`
Update	`PATCH /v3/webhooks/{endpoint_id}`
Delete	`DELETE /v3/webhooks/{endpoint_id}`

Scopes: fax:webhook:read / fax:webhook:edit, or fax:all:read / fax:all:edit.

Legacy `/hooks` API

Legacy webhooks (/v3/hooks) will be decommissioned soon. Use /v3/webhooks for new integrations.

GET/POST /v3/hooks and DELETE /v3/hooks/{hook_id} remain available. Each hook has one event, a target URL, and optional numbers (owned numbers only). See List user webhooks (Legacy).

Get Started

MCP

Concepts

SDKs

API Reference

Definition

Events

Setting up webhooks

Number filters (`channels`)

Handling webhook notifications

Verify signatures

Where to get the secret

Headers

How to verify

Optional: allowlist source IPs

Payload

fax_sent

Payload schema

fax_received

Payload schema

fax_page_received

Payload schema

Handling the notification

Idempotency

API reference

Legacy `/hooks` API

​Definition

​Events

​Setting up webhooks

​Number filters (channels)

​Handling webhook notifications

​Verify signatures

​Where to get the secret

​Headers

​How to verify

​Optional: allowlist source IPs

​Payload

​fax_sent

​Payload schema

​fax_received

​Payload schema

​fax_page_received

​Payload schema

​Handling the notification

​Idempotency

​API reference

​Legacy /hooks API

Definition

Events

Setting up webhooks

Number filters (`channels`)

Handling webhook notifications

Verify signatures

Where to get the secret

Headers

How to verify

Optional: allowlist source IPs

Payload

fax_sent

Payload schema

fax_received

Payload schema

fax_page_received

Payload schema

Handling the notification

Idempotency

API reference

Legacy `/hooks` API