Receiving Delivery Status via Webhook

In this section, we will provide instructions on how to set up DLR Webhook and receive delivery receipts from operators.

Unifonic provides SMS delivery status tracking with a webhook solution. Webhooks are user-defined HTTPS callbacks. They are usually triggered by some event, such as receiving an SMS message by the end-user handset or an incoming WhatsApp Business message.
When that event occurs, Unifonic makes an HTTPS POST request to the URL configured by the customer for the webhook. SMS Delivery status is tracked based on DLR (Delivery Receipt) – a signal that Unifonic receives from mobile operators.

There are Positive DLR and Negative DLR signals that we can receive from a mobile operator.

  • Positive DLR is a confirmation that SMS has been received by the mobile handset. Normally it means that an end-user has been notified about an incoming message by their mobile phone. This signal does NOT specify whether a message has been opened and read by the human.

  • Negative DLR is a confirmation that SMS has NOT been delivered to the mobile device because of various reasons which are out of Unifonic's control.



  1. An example of a reason for receiving a Negative DLR could be Absent Subscriber i.e. when a handset has been out of coverage for 48 hours or more and the mobile operator has dropped the message.
  2. If the end user’s mobile device is switched off, the message is attempted to be delivered when the end user’s handset is switched on and can once again receive messages. For example, a handset would be able to receive messages again upon re-entering a coverage area or turning off Airplane Mode.



A mobile operator might not send us the delivery receipt for a message, in that case the delivery status via webhook is not triggered.

For more information on the delivery states see Understanding SMS Delivery

How To Set Up a DLR Webhook

  • At the moment (September 2022) any customer can request to enable DLR Webhook via Unifonic Customer Support. Customer will need to provide HTTPS endpoint capable of accepting POST requests from Unifonic.

Request Parameters

  • This is an example of POST request payload Unifonic will send to the DLR Webhook indicating a successful SMS delivery:
     "body": {
         "deliveredUnitCount": "1",
         "doneDate": "20220904162355",
         "errorCode": "000",
         "finalStatus": "DELIVRD",
         "freeText": "webhook",
         "id": "127011000000026C20001400018308ABE67E003E6D",
         "messageId": "41000347193391",
         "submitDate": "20220904162347",
         "submitUnitCount": "1"
  "timeStamp": "2022-09-04T13:23:56.487581Z",  
  "eventName": "dlr",  
  "productName": "sms",  
  "accountId": "de6fb171-a55d-45e8-8be6-7df00865bacc"
  • Here is an example of delivery receipt indicating non-delivery from the operator's side:
  "body": {
    "deliveredUnitCount": "1",
    "doneDate": "20220809134254",
    "errorCode": "000",
    "finalStatus": "UNDELIV",
    "freeText": "Hello",
    "id": "127011000000026B800008500182823318FC00xxxx",
    "messageId": "4100033113xxxx",
    "submitDate": "20220809134244",
    "submitUnitCount": "1"
  "timeStamp": "2022-08-09T10:42:56.648988Z",
  "eventName": "dlr",
  "productName": "sms",
  "accountId": "de6fb171-a55d-45e8-8be6-7df00865xxxx"
deliveredUnitCountA number of SMS parts delivered to the mobile device
doneDateA timestamp in mobile operator's SMSC timezone when a message has been delivered to the mobile device. Can be used for end-to-end delivery latency calculations given the timezone is taken into account.
errorCodeCurrently not used, will be used for non-delivery error code indication in the future updates
finalStatusDELIVRD or DELIVERED means that the mobile operator indicated the SMS has been delivered to the end user's mobile device
freeTextA fragment of the original SMS message body - for troubleshooting purposes
idSMS segment ID
messageIdUnifonic message ID
submitDateA timestamp in mobile operator SMSC timezone when a message has been submitted to the mobile operator by Unifonic or one of the Unifonic's partner providers
submitUnitCountA number of SMS part submitted
accountIdCustomer's account ID in Unifonic
timeStampA timestamp in UTC when the delivery receipt was received from operator, can be used for approximate end-to-end delivery latency calculations
eventName"dlr" - for SMS delivery receipt
productName"sms" - for SMS delivery receipt