Outbound JSON Delivery Notification

AirComUSA/Faxpipe
Abstract
This document describes JSON result notification format for outbound fax delivery.

Legal Notices
The information contained herein is subject to change without notice and is not warranted to be
error-free. If errors are found, please report them to us in writing.

AirComUSA and Faxpipe are registered trademarks of AirCom LLC (AirCom), and shall not be
used without AirCom's express written authorization.

Use of this documentation is subject to the following terms: You may create a printed copy of
this documentation solely for your own personal use. Conversion to other formats is allowed as
long as the actual content is not altered or edited in any way. You shall not publish or distribute
this documentation in any form or on any media, except if you distribute the documentation in a
manner similar to how AirCom disseminates it. Any other use, such as any dissemination of
printed copies or use of this documentation, in whole or in part, in another publication, requires
the prior written consent from an authorized representative of AirCom. AirCom reserves any
and all rights to this documentation not expressly granted above.

This document refers to JSON postback response for outbound faxing.

2
Delivery Notification Postback Responses

The faxing system will automatically post back data regarding delivery results to the reconfigured
customer response api endpoint. The customer account can be set to 1) send a notification after each
faxing attempt or 2) to send a single notification after the fax has been delivered or all attempts have been
made.

What is needed from customer:

 The frequency of notifications: per attempt or after completion.

 Notification endpoint, for example https://example.com/fax/statusupdate
 User name to be used in the Authorization header.
 Shared hash key to be used to calculate the HMACSHA1 authorization value, for example
H484T9nQ14Fr2yIGGOk8vGB1oR5QKF0K

The response is Content-Type: application/json with an Authorization header.

POST <POST page> HTTP/1.0
Host: <domain.com>
Content-Type: application/json
Content-Length:<data length>
Authorization: <base64 encoded “user <user name>:base 64 encoded “<hash value>””>

{ <json data> }

JSON data format

The json-data is formatted as follows:
{
"aircomAccount":(String),
"clientId":(String),
"aircomId":(String),
"totalPages":(Number),
"notificationType":(String),
"faxResults": [
{
"faxDelivered":(Boolean),
"faxNumber":(String),
"faxAttempts": [
{
"dateTime":(Number),
"deliveredPages":(Number),
"duration":(Number),
"statusCode":(Number),
"statusReason":(String)
} ]
} ]
}

3
Explanation of JSON data:

"aircomAccount":"00000" (String) AirCom assigned account number.

"clientId":"SomeID" (String) The client identifier assigned as subject of the submission.

"aircomId":"SomeString" (String) Unique AirCom ID for this request.

"totalPages":1 (Number) Total pages expected to be faxed.

"notificationType":"complete|attempt|final" (String) Indicates the type of notification.

 complete – Used when only one notification is given after all attempts are made. The notification will include all
attempt results.
 attempt – Used when notification is given after each attempt. The notification will include only one attempt result
which was not successful.
 final – Used when notification is given after each attempt. The notification is the final attempt and may indicate a
successful delivery or a failure. No further attempts/notifications are made.

"faxResults" (Array) Contains one or more fax number data sets.

"faxDelivered":true (Boolean) The delivery status for the given "faxNumber"

"faxNumber":"8015550000" (String) Given fax number.

"faxAttempts" (Array) Contains one or more fax attempt data sets.

"dateTime":1427781600 (Number) Unix epoch time.

"deliveredPages":1 (Number) The number of pages delivered during the attempt.

“duration”:48 (Number) The duration of the fax attempt, in seconds.

"statusCode":10 (Number) Status code. Numeric value.

"statusReason":"Busy" (String) The description of the status.

statusCode statusReason
----------------------------
0 Unknown
1 No Answer
2 Busy
3 Operator Intercept
4 Connect
5 Connect - Voice
6 Connect - Fax/Data
7 Connect - Ans Machine
8 Bad phone number
9 Connect - Fax Incomplete
10 Connect - Delivered
11 Connect - Voice/Machine
12 Connect - Fax Error
13 Connect - Equipment Busy
14 Blocked

4
Calculating Authorization Header
The HMACSHA1 hash value is calculated on the string <endpoint url>?< the json data minus white
space>. The "Authorization:" string is base64 encoded "user <user name>:base64 encoded “<hash
value>”". Note that the hash value is first base64 encoded and then the whole string including the user
name is again base64 encoded. Also note the space between “user” and the <user name>.

The following pseudo code steps can be used to calculate the authorization header.

 user_name = “some_name”
 endpoint = “some_url” For example https://example.com/fax/statusupdate
 hash_key = customer_supplied_sharedKey
 json_data = removeWhitespace(receivedJSONdata)
 tobe_hashed = endpoint + “?” + json_data
 signing_key = getSecretKey(hash_key, HMAC_SHA1_ALGORITHM)
 hash_value = signMAC(signing_key, tobe_hashed)
 b64_hash_val = base64Encode(hash_value)
 auth_string = base64Encode(“user ” + user_name + “:” + b64_hash_val)

Once the authorization string has been calculated, it is compared with the string in the “Authorization”
header to ensure that the POST came from Faxpipe and that the data was not modified in transit. After
the post has been successfully authorized and accepted, Faxpipe expects “200 OK” in the reply headers.

Example – This is only a representation of what is posted and the authorization string is only an example and not a real value
based on the information below. During customer development and testing, Faxpipe will be sending actual real data that can be
used to verify correct customer side implementation.

POST /fax/statusupdate HTTP/1.0

Host: example.com
Content-Type: application/json
Content-Length: 338
Authorization: dXNlciBhaXJjb206Q0ZNTUF6MlZOREprL1VOZjhob1NlQlljZiswPQ==

{ "aircomAccount":"00000", "clientId":"SomeID",
"aircomId":"E2F00012345678901234", "totalPages":1,
notificationType":"complete", "faxResults": [ { "faxDelivered":true,
"faxNumber":"8015550000", "faxAttempts": [ { "dateTime":1427533322,
"deliveredPages":1, "duration":48, "statusCode":10, "statusReason":"Connect -
Delivered" } ] } ] }