Delivery Receipt (DLR)

Delivery Receipt (DLR), also known as SMS Delivery Status Report. It is a service for developers to programmatically obtain the status of SMS delivery, Unimatrix supports proactive pushing of SMS status reports via Webhook.

Settings

This feature is an extension service and is not enabled by default. Please go to Extensions - Delivery Receipt in the Console to configure according to your actual needs.

Set the Webhook URL for receiving status reports and specify the request body data format you need to receive, supporting JSON or XML, default is JSON. That completes the basic configuration and is ready for access.

Integration

Unimatrix will send an HTTP request to the Webhook URL you set with the POST method, with the body of the request in JSON format for example.

Request Body

Example content is as follows:

{
  "id": "78c038133e6ac2b6d8a0844c42f57dac",
  "status": "delivered",
  "to": "+12060000123",
  "iso": "US",
  "cc": "1",
  "parts": 1,
  "price": "0.018900",
  "currency": "USD",
  "errorCode": "DELIVRD",
  "errorMessage": "Delivered",
  "submitDate": "2021-08-29T00:19:17.702Z",
  "doneDate": "2021-08-29T00:19:20.011Z",
}

Response

A response with HTTP Status Code 200 is considered a successful status report, and Unimatrix does not perform additional checks on the response load.

Signature verification

To further secure your data, Unimatrix supports configuring signatures to verify that Webhook requests come from Unimatrix and that the data has not been tampered with during transmission. Simply enable "Signature Verification" in the settings page and set the signature key (Secret).

When signature verification is enabled, Unimatrix will carry the Authorization field in the Webhook request header with the value constructed in the format UNI1-HMAC-SHA256 Timestamp={unix_epoch}, Nonce={nonce_str}, Signature={signature}, as shown in the following example:

Authorization: UNI1-HMAC-SHA256 Timestamp=1630196360, Nonce=84100f131d7096ee, Signature=W7MNfb0bxRTfgPsxP9rOoZuNLm9+hkY68f/sq9TyHS8=

Extract the Timestamp, Nonce fields and convert their field names to lowercase and add them to the request payload, sort them in dictionary order (ASC) according to the parameter Key, connect the Key-Values with = and the parameter pairs with & to form the text string to be signed, example is as follows:

cc=1&currency=USD&doneDate=2021-08-29T00%3A19%3A20.011Z&errorCode=DELIVRD&errorMessage=Delivered&id=78c038133e6ac2b6d8a0844c42f57dac&parts=1&nonce=84100f131d7096ee&price=0.018900&iso=US&status=delivered&submitDate=2021-08-29T00%3A19%3A17.702Z&timestamp=1630196360&to=%2B12060000123

Using the HmacSHA256 algorithm, a signature is generated on the text string to be signed with the set signature key (Secret), and the output is a Base64 string, as shown in the following example:

W7MNfb0bxRTfgPsxP9rOoZuNLm9+hkY68f/sq9TyHS8=

The Signature value extracted from Authorization is compared with the generated signature, and the verification is successful if it matches.

Mock Testing

For quick integrate by developers, Unimatrix has kindly provided Mock testing functionality. You can send mock-constructed DLR requests directly to the target server via the console.

Re-pushing

After the first push status report fails, Unimatrix will still re-push the message to the target URL until the push is successful or the maximum number of pushes is exceeded. The re-push interval is 1 minute, 5 minutes, 10 minutes, 30 minutes, 1 hour.