Methods for Receiving Faxes

There are two primary methods for receiving faxes in the eFax® Enterprise API. Users can:

  1. Pull faxes using the GET /faxes/received endpoint in the API.
  2. Use the Webhook Notification Function to obtain faxes through an auto-posted URL notification.

Each of these methods uses the OAuth protocol for secure authentication and authorization. Refer to the Obtaining Authentication Credentials section of the Getting Started Guide.

The following sections describe each of these options.

Use the GET /faxes/received Endpoint in the API

This method allows the eFax Enterprise API user to pull their own inbound faxes based on selected query parameters. The advantage of this approach is that it allows users to take advantage of “out-of-the-box” API functionality to set customized polling intervals (within certain limits) to meet specific business needs.

For example, if users receive a constant stream of faxes throughout the day they can call this endpoint every 30 seconds to keep up with the steady inbound flow of traffic. Conversely, if the need is not as severe, the polling interval could be set for every four hours so that faxes are pulled in bulk six times in a 24 hour period or three times during a business day (for example, 8 a.m., 12 noon, and 4 p.m.).

Use the endpoint parameters to customize your request. For example:

  • Use the min_completed_timestamp parameter to set a date and time and only get faxes back after that threshold.
  • Set the image_downloaded parameter to FALSE to get a list of faxes you have not yet downloaded.
  • Use the search_text field to search a text string in the fax metadata.
  • To determine if more than 100 faxes are available for download, use the pagination-offset and pagination-limit fields in the Request Header. Refer to the GET /faxes/received endpoint in the API Specification for usage details.

Client-side storage and final disposition of downloaded faxes is up to the user, using client-side routing instructions to get the faxes to their proper destination. Making this call does not delete the faxes from our storage (this is accomplished using the DELETE /faxes call). Similarly, the polling interval used to download faxes is set on the client side and not in the API.

Use the Webhook Notification Function

This method allows eFax Enterprise API Admins to provide a secure destination URL, of their choosing, where inbound faxes notifications are auto-posted. These notifications include a separate link to download the fax. HTTPS is required when setting up the destination URL.

The advantage of this approach is that it is more of a set it and forget it approach than the received endpoint. Once setup, inbound faxes flow into your application, as received, to the designated URL. From there the client can program any required backend actions/routing based upon metadata posted to the URL. An example of a customized notification URL is:

https://100.200.300.400/InboundFaxService/InboundFaxService.svc/AcmeWidgets/Receive

We also support HMAC authentication for our webhooks using SHA256 hash encryption.

Ports

Our service allows customers to specify the URL for webhook delivery.

No port number needs be specified in setting up your webhooks; we use 443 by default. For example: https://api.example.com/webhook/path. If you have a need for an alternative port, we allow :8443. For example: https://api.example.com:8443/webhook/path.

Any webhook configuration that doesn't follow these guidelines will not be delivered.

JSON Payload

The following is an example of the JSON payload delivered to the user’s notification endpoint.

{
   "app_id": "d580162d-d162-4353-bd55-c2044ab20711",
   "user_id": "ca4cd102-c3e7-4379-9a7e-38c61e1f7a55",
   "notification_id": "c1378358-e733-4732-aae6-73f8127af416",
   "direction": "INBOUND",
   "completed_timestamp": "2024-05-10T17:54:11Z",
   "duration": 48,
   "pages": 2,
   "fax_id": "7e029808-237b-413e-a051-53bf445e8b49",
   "sending_fax_number": "13235555555",
   "receiving_fax_number": "18885555555",
   "resource_url": "https://api.securedocex.com/faxes/7e029808-237b-413e-a051-53bf445e8b49/image"
   "originating_fax_tsid":"18664226438"
}

Client Response

The client should respond with a 200 OK if the delivery is a success. The client provided response body must use Content-Type:application/json format; however, any response body is permissible as long as it is in JSON format. For example:

HTTP/1.1 200
Content-Type: application/json
{
   "status": "SUCCESS"
}

Downloading Images

To download the actual image via the resource-url the client will also need to provide:

  • The provided user-id of the given fax.
  • Bearer Token for the given app_id.

In conjunction with this webhook approach, the client should use the existing API endpoint GET /faxes/received with the parameter image_downloaded set to FALSE to retrieve a list of faxes not yet downloaded. Those faxes can then be manually download via the API call GET/faxes/{fax_id}/image.

Testing Webhooks

We now support the ability to test a webhook via the POST /notifications/ping endpoint. For example:

POST https://api.securedocex.com/notifications/ping
{
    "fax_direction": "INBOUND" #OUTBOUND
}
Response:
[
  {
    "app_id": "xxxx",
    "notify_id": "7b692d22-c7cf-11eb-9e0a-83dcedf47a3d",
    "notify_config_id": "xxxxx-182f-xxxx-ab9a-xxxxxxxxxxxx",
    "fax_direction": "INBOUND",
    "notify_type": "WEBHOOK",
    "event_type": "PING"
  }
]

The User will also get a webhook post request to the configured URL with payload:

{
    "app_id": "xxxx",
    "notification_id": "7b692d22-c7cf-11eb-9e0a-83dcedf47a3d",
    "direction": "INBOUND", 
    "event_type": "PING",
    "notification_config_id": "xxxxx-182f-xxxx-ab9a-xxxxxxxxxxxx"
}

Fax Services API Spec — Test Notification Configuration

Notes

For the Webhook Notification Function:

  • The fax routes to the URL at the account level. Using fax metadata information packaged with each notification, custom client-side routing rules send the fax to the proper fax owner within that account (by User ID for example). Retry logic is also part of the JSON payload associated with each notification; if the initial call fails to post we make five retries with five-minute intervals between retry attempts.
  • All fax images are Base64 encoded. Future versions may include notification links to authorization-protected S3 buckets where PDF or TIFF images can be stored for a specified amount of time.

Webhook Best Practices

Keep the following best practices in mind when using the Webhook notification method:

Event Handling

Do not complicate notification logic by attempting to instigate a download on top of any notification instance. Notifications have a (very) short shelf life by design; think of them as a simple notice that should not handle other events.

Duplicate Events

Duplicate notification events (multiple simultaneous notifications for one fax) are rare, and should not inhibit the ability to download the fax in question. If duplications are a concern, users may insert logic into their Webhooks that will deal with them appropriately.

Users should keep in mind that sequential arrival of notifications is not guaranteed, and cannot be enforced by additional logic.

Security

All images must be downloaded from our API in a secure manner. The resource_url field in the JSON payload delivered to the user’s notification endpoint WILL ALWAYS reference our API domain (https://api.securedocex.com/). Users should ensure that they take steps to prevent spoofing of Webhook notifications, including not accepting notification payloads referencing other domains.

 

HMAC Webhook Header

HMAC (Hash-based message authentication code) is a message authentication methodology that uses a cryptographic key in conjunction with a hash function. HMAC may be used to simultaneously verify both the data integrity and the authenticity of a message.

We support HMAC authentication for our webhooks using SHA256 hash encryption. The eFax Enterprise API notification service and client each should be provided with a private key that is known only to the service and to the specific client. The private key should be provided by the client during configuration of the WebHook URL.

On each WebHook event request to the client endpoint the notification service will be generating a unique HMAC, or hash, by hashing the request data with the private key and sending it as part of the request in request headers. When the client receives the WebHook event they should be using the same hash function and private key to generate the hash code from the payload on their end and compare it with the received one.

To use HMAC authentication, the client must use the x-HMAC-Signature to validate webhooks. Validate the signature using HMAC best practices. Contact your account manager, sales engineer, or customer support to enroll in HMAC.

Java Code Sample:

import org.apache.commons.codec.binary.Hex;
import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

String hmacSecret = ...; // HMAC secret set in Notify Configuration
String payload = ...; // WEBHOOK JSON body payload
String payload = ...; // WEBHOOK JSON body payload
String hmacSignature = header.getFirst("X-HMAC-Signature"); // HMAC signature

Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(hmacSecret.getBytes(), "HmacSHA256"));
byte[] hmac = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
bool isEqual =  MessageDigest.isEqual(hmac, hmacSignature.getBytes(StandardCharsets.UTF_8)); // PREVENT timing attacks
return isEqual

NodeJs Code Sample:

import { createHmac } from 'crypto';
const hmacSecret = ...; // HMAC secret set in Notify Configuration
const payload = ...; // WEBHOOK JSON body payload
const hmacSignature =  req.headers.get("X-HMAC-Signature") // HMAC signature
const hmacHash = createHmac('SHA256', hmacSecret)
       .update(payload)
       .digest('hex');
return crypto.timingSafeEqual(Buffer.from(hmacHash, 'utf8'),Buffer.from(hmacSignature,'utf8')) // PREVENT timing attacks

 

Return to the top of this page.