Use the GET /notifications Endpoint

Webhooks allow admins to provide a secure destination URL, of their choosing, where received or sent fax notifications are auto-posted by the API. The advantage of this approach is that this allows you to configure your applications to pick up this information and route through your workflows as needed.

The GET /notifications endpoint allows eFax Enterprise users to determine the operational status (success, failure, or queued) of their inbound or outbound webhook notifications.

There are two usage options for the GET /notifications endpoint, calling an empty endpoint to return a record of all notifications, regardless of status, or setting parameters to customize and narrow your search.

Calling the GET /notifications Endpoint Without Parameters

Using this endpoint without request parameters (empty) returns a list of ALL successful, failed, and queued webhook notifications for both inbound and outbound faxes. For inbound faxes, these webhooks allow you to download the actual fax, whereas for outbound faxes, each notification contains fax metadata for each sent fax.

Calling the GET /notifications Endpoint With Parameters

To avoid large responses containing data that must be sifted though, you can use request parameter filters to customize the search based on fax direction, sent status, and time stamps. For example, to find all failed outbound webhook notifications (without regard to a particular date range), you would call (GET https://api.securedocex.com/notifications) with the following fields set:

{
  "sent_status": "failed"
  "fax_direction": "outbound”
}

This returns:

[
  { 
    "app_id": "12345",
    "user_id": "12345678-87654321",  
    "fax_id": "3f3123e2c-ff29-8ca3-02e5-8f0f87cb8ebb",
    "notify_id": "ed43b4e5-cdc5-bf9e-90cb-7945af0aa135",
    "fax_direction": "OUTBOUND",
    "fax_completed_timestamp": "2024-05-10T15:07:01.000Z",
    "notify_type": "WEBHOOK",
    "notify_destination": "https://some.host.url",
    "sent_status": "FAILED"
  },
  {
    "app_id": "12345",
    "user_id": "87654321-12345678",
    "fax_id": "746325a7-0470-4f49-2780-9e3a167b8611",
    "notify_id": "fd093799-128c-afbc-2e5d-b8d6638880b3",
    "fax_direction": "OUTBOUND",
    "fax_completed_timestamp": "2024-05-10T15:07:01.000Z",
    "notify_type": "WEBHOOK",
    "notify_destination": "https://some.host.url",
    "sent_status": "FAILED"
  }
]
....

Webhook Best Practices

The eAPI webhooks serve as notification alerts to the user that faxes/information is available.

We post webhooks to the customers desired endpoints 5 times (the initial attempt, then an additional 4 attempts over a 20 minute period). For each notification, the customer application has 10 seconds to respond (meaning we wait 10 seconds per webhook attempt). If we get no response from the customer side after 10 seconds, the webhook will timeout. To avoid duplications of fax notifications, it is important that users acknowledge the notification on their side as soon as possible and asynchronously download the fax/metadata.

Keep in mind that Consensus is only responsible for posting the notification saying that a new inbound fax is available or what the status is of an outbound fax; webhook failures should be handled on the customer side, as well as any retry attempts. Customers should monitor webhook status via the GET /notifications endpoint. We recommend running query /notifications for FAILED only after our original 20 minute window is completed; if run before that time is up then it is possible to get duplicate notifications. Ideally, your workflows should only mark notifications as FAILED after all retry attempts are completed from our side.

Actions to Take If You See Failed Webhooks

If the GET /notifications endpoint does webhooks with a “sent_status” of “FAILED”, you have two ways to recover:

Option 1 - Use the response from GET /notifications, grab the failed FaxIDs and manually pull status of these faxes via the retrieve a fax’s metadata call.
Option 2 - Use our re-trigger webhook endpoint and we will re-attempt the webhook notifications.

Be sure to use either of these options only after our retry window is closed (20 minutes after the original notification, or 5 attempts in total).

Return to the top of this page.