Receive an SMS Delivery Report using Infobip API

As an outcome of this guide, you will receive a Delivery Report of a sent SMS using Infobip API and an online free webhook tool. Once configured, for every SMS sent, you will get a delivery notification sent real-time to an endpoint you have specified for that SMS sender.

Depending on the amount of information you wish to receive, you'll be able to choose between two methods of setting up Delivery Reports programmatically, through the SMS API or through the Subscriptions Management API.

NOTE

For ease of replicating the scenario, we have used a free online webhook tool, HookRelay (opens in a new tab). You may replace HookRelay with your own hook server.

Prerequisites

Infobip account (opens in a new tab). If you do not have one, you can create a free trial account (opens in a new tab).
Infobip API key with sms:message:send scope. Find out more about how to create an API key with the correct scope .
Your favorite HTTP client. In this example, we will use curl. Additionally, you can choose the official Infobip SDK for your preferred programming language.
Sender. If in the free trial period, use Infobip test sender, ServiceSMS. To configure a custom sender, request a new number or an alphanumeric sender through the Infobip account (opens in a new tab) or using Infobip Numbers API (opens in a new tab).
Destination - a phone number to which the message will be sent. If in the free trial period, you can only send messages to your verified phone number.

Summary of the steps

Set up a webhook.
Optionally, create a subscription and specify events you want your webhook to listen to.
Send an SMS.
Receive a Delivery Report in real time.

Set up a webhook

For the purpose of this guide, we will use a simple online webhook tool, HookRelay (opens in a new tab). This section will show you how to create an account and configure the webhook with HookRelay.

Step 1. Sign in with git credentials

Sign in to HookRelay (opens in a new tab) with your GitHub or GitLab credentials. Once logged in, you'll access a dashboard where you can start creating webhooks.

Step 2. Create a webook

To create an inbound webhook, from your dashboard, click the New Hook button on the top right. That will take you to the configuration screen where all you need providing is a descriptive name for your webhook, e.g. Infobip SMS Delivery Reports.

Once you click the Create hook button, you'll be able to view and copy its URL that you will need to provide in your SMS payload, so the Infobip platform knows where to send its delivery reports. You'll do that for each SMS you wish to receive delivery reports for.

Create a subscription

Skip this step if you don't want to use subscriptions.

Subscription Management API allows you to have control over which events you want to be notified about or if you want to specify different webhooks for different use cases. To use this feature, you'll need to add a scope, subscriptions:manage to your API Key.

Use the Create subscription (opens in a new tab) endpoint to allow for the incoming traffic.

curl

curl -L -g 'https://6jnngr.api.infobip.com/subscriptions/1/subscription/SMS' \
-H 'Authorization: {authorization}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "subscriptionId": "SMS1234",
  "name": "Default group",
  "events": [
    "DELIVERY",
    "CLICK",
    "INBOUND_MESSAGE"
  ],
  "profile": {
    "profileId": "NOTIF-323956",
    "webhook": {
      "notifyUrl": "https://api.hookrelay.dev/hooks/jogep17l25r0hejdnkwzx830/18a3213426f698fd2231b847"
    }
  }
}

Key points:

Use events to specify the events you want to receive on your webhook.
Use profile to provide the URL to your webhook and additionally, if needed, set up security settings.

Once the subscription is created, you'll get a 201 CREATED response.

{
    "subscriptionId": "SMS1234",
    "profile": {
        "profileId": "NOTIF-323956"
    }
}

From that moment on, the webhook specified in the subscription will catch the events you subscribed to.

Send an SMS

Send an SMS as you would normally do. There's a slight difference how you do it, based on whether you have set up a subscription or not.

With a subscription

Use the Send SMS message (opens in a new tab) endpoint like you'd typically do. The URL you have provided in your subscription will catch the events you have subscribed for.

curl

curl -L 'https://6jnngr.api.infobip.com/sms/3/messages' \
-H 'Authorization: {authorization}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "messages": [
    {
      "sender": "InfoSMS",
      "destinations": [
        {
          "to": "447415774332"
        }
      ],
      "content": {
        "text": "This is a message I want to get a report about."
      }
    }
  ]
}'

Without a subscription

Send an SMS as you would normally do, but additionally use the webhooks object to pass in the URL you want your report to be sent to.

curl

curl -L 'https://6jnngr.api.infobip.com/sms/3/messages' \
-H 'Authorization: {authorization}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "messages": [
    {
      "sender": "InfoSMS",
      "destinations": [
        {
          "to": "447415774332",
          "messageId": "MESSAGE-ID-123456"
        }
      ],
      "content": {
        "text": "This is a message I want to get a report about."
      },
      "webhooks": {
        "delivery": {
          "url": "https://api.hookrelay.dev/hooks/jogep17l25r0hejdnkwzx830/18a3213426f698fd2231b847"
        },
        "contentType": "application/json",
        "callbackData": "DLR callback data"
      }
    }
  ]
}

Key points:

If for some reason your webhook was not available to receive traffic, Infobip platform will make several attempts to communicate with it.

Receive a Delivery Report

Once your message has been sent, you should get an event on your webhook. Typically, this would be a message saying that your SMS has been delivered to a handset. See the Response Status and Error Codes documentation to view other possible message statuses or errors that will help you troubleshoot any potential issue you may encounter.

Report with a subscription

The report is tailored to what you have subscribed for for the particular channel.

{
  "results": [
    {
      "bulkId": "BULK-123-ABC",
      "price": {
        "pricePerMessage": 0.0,
        "currency": "EUR"
      },
      "status": {
        "id": 5,
        "groupId": 3,
        "groupName": "DELIVERED",
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "error": {
        "id": 0,
        "name": "NO_ERROR",
        "description": "No Error",
        "groupId": 0,
        "groupName": "OK",
        "permanent": false
      },
      "messageId": "MESSAGE-ID-123456",
      "doneAt": "2025-05-23T10:47:27.807+0200",
      "smsCount": 1,
      "sentAt": "2025-05-23T10:47:26.285+0200",
      "to": "447415774332"
    }
  ]
}

Report without a subscription

The report contains all available data.

{
  "results": [
    {
      "bulkId": "BULK-123-ABC",
      "price": {
        "pricePerMessage": 0.0,
        "currency": "EUR"
      },
      "status": {
        "id": 5,
        "groupId": 3,
        "groupName": "DELIVERED",
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset",
        "action": null
      },
      "error": {
        "id": 0,
        "name": "NO_ERROR",
        "description": "No Error",
        "groupId": 0,
        "groupName": "OK",
        "permanent": false
      },
      "messageId": "MESSAGE-ID-123456",
      "doneAt": "2025-05-23T10:52:13.624+0200",
      "messageCount": 1,
      "sentAt": "2025-05-23T10:52:12.384+0200",
      "callbackData": "DLR callback data",
      "to": "447415774332",
      "sender": "447860064050",
      "platform": {
        "entityId": null,
        "applicationId": null
      }
    }
  ]
}