Receiving message delivery reports via webhook

You can specify an HTTP(S) address in your account settings for a webhook that will be called from our side whenever a new delivery report comes in for a message sent through your API account.

You may want to whitelist our addresses in order to be able receive these requests, depending on how tightly your firewall is locked down.
The address you specified for your will receive HTTP POST requests with these parameters:

MSSID: SMS ID, received from SendOne, SendMultiple, or AddBatchRecipients commands.
DLR: Delivery report, one of these values:
- Delivered: SMS was delivered successfully.
- Sent: SMS was sent but it is not yet known if it was delivered.
- Buffered: SMS has been passed on but is still waiting for delivery (or delivery report is not yet received.)
- Undelivered: Not possible to deliver the message
- Error: Error of our system or the operator.
- Other: Other unknown delivery report.
Error and Other reports shouldn’t normally occur at all.
Expired (0/1): If the message wasn't delivered (Undelivered status report,) indicates if it was because the message expired (the recipient phone number is valid but wasn't rechable during message validity period.)
HMAC: Authentication code for report verification

Detailed description about the meaning specific delivery reports can be found here: Meaning of SMS delivery reports.

Report webhook request verification

In order to ensure these webhook requests are authentic, you can check the source IP address to see if it is one of ours but additionally these requests now include an authentication code that can be used to verify the report.
The authentication code is what's known as an HMAC. It is computed using the SHA-256 hash function and it will be a text string containting 64 hexadecimal characters.
The value is derived from your API key, message identifier (MSSID) and delivery report value (DLR) like this:

HMAC = SHA-256( APIKEY + SHA-256( APIKEY + MSSID + DLR ) )

If the received value matches what you can compute on your side upon receiving the request, you can be reasonably sure that the data has not been tampered with.

PHP example for computing the HMAC value when receiving the request

// This assumes the $_POST values are populated correctly so no validation code is included.
$api_key = 'YOURAPIKEYHERE';
$hmac = hash('sha256', $api_key.hash('sha256', $api_key.$_POST['MSSID'].$_POST['DLR']));

if ($hmac == $_POST['HMAC']) {
    // Request is valid
}

Updated on: 11/01/2023