How to Track Fax Delivery in Your Application

After your application submits a fax, users need to know what happened. Did it arrive, is another attempt underway, or does someone need to investigate?

With the Fax.Plus API, you can answer those questions by connecting the send response, webhook notifications, and fax records to the same application task. This guide explains how to build that tracking workflow, including what to do when an update is delayed or a fax is retried.

Before you start

The Fax.Plus REST API requires Enterprise API access. Confirm your account's access and choose an authentication method before building the integration. Your token also needs permission for each operation you use. These REST API requirements are separate from MCP access.

For the webhook-based workflow below, you'll need an HTTPS endpoint. A webhook is an HTTP notification Fax.Plus sends to your application when a fax event occurs.

For broader decisions about account setup, authentication, and launch planning, start with Fax API Production Planning. The steps below focus on tracking a fax after submission.

Save the identifiers returned when you send

Create an application job before submitting the fax. Give it your own business reference, such as an order ID, and record the destination, document version, submission time, and API account. Keep confidential document contents out of identifiers and routine logs.

The send endpoint supports return_ids: true. Its response includes an ids mapping from destination numbers to fax IDs. Save each destination-and-ID pair against your job. A fax sent to several recipients needs a result for each recipient.

Keep these identifiers separate:

• Your application's business reference.
• The original fax ID returned for each destination.
• The fax and session IDs received in later notifications.
• The HTTP delivery ID used to recognize a repeated notification.

This matters when a fax is retried. The webhook schema distinguishes hook.id from data.id. The latter identifies the fax session, can change on a retry, and may differ from the ID in a fax listing. Preserve both fields and verify how they relate to your submission and result records.

Also plan for a send request that times out. Your application may not know whether Fax.Plus accepted it. Keep that job unresolved and investigate before submitting it again; a client timeout alone doesn't establish that no fax was sent.

Subscribe to completion events

For a new integration, use POST /v3/webhooks and subscribe to fax_sent. This event means an outbound session finished, including an unsuccessful session. Read data.status to determine the result.

Enable webhooks in the account's Integrations settings, then create an endpoint with your HTTPS receiver url and the required filter_types. The endpoint creation reference lists fax:webhook:edit or fax:all:edit permission. Where your architecture allows it, keep webhook setup permissions separate from the permissions your running application needs.

Use the current endpoint reference rather than adapting an older /v3/hooks example.

Save each notification before processing it

Keep the receiver's job small: verify the request, save a processing task, and respond promptly. A background worker can then update the application and send any necessary user notifications.

Verify the request

Follow the signature verification instructions, including verification against the original request bytes and a timestamp check. Verify the request before trusting its contents.

Copy the endpoint-specific signing secret from Webhooks → Manage → Advanced → Signing Secret in the web app, and keep it in approved server-side secret storage. The REST API does not return that secret. Web app webhook management requires an Owner or Admin, as the webhook Help guide explains.

Make repeated delivery safe

Use the webhook-id HTTP header to identify a notification delivery. It serves a different purpose from the fax and session IDs in the JSON body. The idempotency guidance explains how this identifier behaves during retries and replays.

A practical receiver follows this sequence:

1. Verify the request and read its delivery ID.
2. Save a new processing task in a database or persistent queue, so it survives a restart.
3. Return HTTP 200 after that task has been saved successfully.
4. Let a worker apply the result and record completion.

Make the check and save atomic: two copies arriving at the same time must not create two tasks. If that delivery is already safely recorded, return 200 without adding it again. If storage fails, don't acknowledge it as safely saved.

The worker also needs to be idempotent, meaning it can process the same task again without repeating the business action. For example, restarting after a status update should not send a second customer notification. These database and queue patterns are application design recommendations, not automatic behavior supplied by Fax.Plus.

Show a useful status for each recipient

Separate submission, transmission, and any business follow-up. A purchasing application might show “Submitted,” then “Fax delivered,” then “Supplier acknowledgment pending.” Those are illustrative application labels: fax delivery establishes a transmission result, while the supplier's response is a separate step.

The Outbox lifecycle includes submitted, converting, scheduled_for_sending, and sending. Use these to show progress while the fax is being processed. None is a successful delivery result.

For completed sessions, map the documented fax statuses to useful next actions:

• A successful transmission can complete the sending task for that recipient.
• A partial transmission needs attention because some pages may already have arrived.
• A busy or unanswered destination may call for a later attempt.
• An invalid number or conversion problem usually needs the input corrected first.

Keep the original status and failure reason for authorized support staff, even if users see simpler wording. “Check the destination fax number” is more useful than an unexplained status code.

Where retries are configured, keep each attempt's result alongside the overall job. An older failure notification must not overwrite a later success. If you can't establish the current outcome, show that it needs verification and give an operator a way to investigate.

Keep fax retries separate from notification retries

A webhook retry sends a notification to your server again. A fax retry makes another transmission attempt to the recipient. Confusing them can send duplicate documents.

Before your application submits another fax, check the existing job, known results, configured provider retries, and your business rule for approving another attempt. The fax retry guidance covers submission-level options and partial-send behavior.

Decide which component is responsible for retries and account for every active retry mechanism. Preserve the relationship between any deliberate new submission and the original job.

Recover missing status updates

Use webhooks for normal updates and add a periodic check for jobs that remain unresolved. This comparison between the API and your application's records is often called reconciliation.

Choose the interval around your workflow. A scheduled fax, a large document, and a job with retries may take different amounts of time. Back off after read errors and follow the API's rate-limit guidance rather than polling in a tight loop.

Start with the evidence you already have:

• For a known fax record, use GET /v3/accounts/{user_id}/faxes/{fax_id}. The record endpoint returns status, page count, and other details. Use the correct account and record ID.
• When necessary, query the fax listing with category=sent and a bounded time range. Read every page before concluding that a record is absent.
• For a fax still being processed, check the Outbox.

Don't assume the original submission ID will always retrieve the latest result after retries. If you need to match a listed record to a job, compare the stored identifiers and destination details. Send ambiguous matches for review rather than guessing from a phone number and timestamp.

The webhook management panel also provides delivery logs and manual replay. Replay can restore a missed notification without retransmitting the fax.

An empty Outbox result doesn't prove delivery, and a failed read request doesn't prove fax failure. Check for authentication, permission, and service errors before changing the user's status.

Test the failure paths

Use controlled documents and agreed destinations to test the whole tracking workflow. Include:

• Successful, failed, and partial transmissions.
• Duplicate notifications and a worker restart after saving a result.
• A missing event recovered without sending another fax.
• A retry whose identifiers differ from the original submission.
• A multi-recipient job with a different result for each destination.
• An invalid signature and expired API access.

These are suggested acceptance tests. The workflow in this article has not been tested end to end.

Start with one complete tracking workflow

Begin with one destination and one application job. Save its identifiers, verify a completion notification, show the correct result, and recover the job when a notification is deliberately withheld. Once that works under controlled tests, expand to your expected volume and exceptions.

‍