1. What are webhooks
2. Creating a webhook / callback URL
3. Receiving notification
4. Retry policy
5. List of webhook events
6. Best practices

What are Webhooks?

With SMS Connexion's webhooks (also called "callback URLs"), developers can set their applications to receive notifications when certain events happen through our services. When an event is triggered, the SMS Connexion API sends an HTTP POST payload to your webhook.

SMS Connexion's webhooks are a simple way for your application to be notified of changes to a specific service without polling the service. Your application will be no longer required to constantly poll for changes.

Creating a webhook / callback URL

There are two ways to register your webhooks to receive event notifications:

1. Admin Dashboard: Go to HTTP API > edit the settings of your Application or API Key and save your callback URLs.

   

2. When making an API request: you can register a webhook by providing the parameter dlrCallbackUrl in the body of your request. In the event that you have registered a webhook via the Admin Dashboard and also provide a webhook in the API call, the one given via the API call will have priority.

   POST /sms HTTP/1.1
   Host: api.sms.cx
   Authorization: Bearer M2ZkOTcxNzZiZDdlMzZjMGU3GmJ...
   Content-Type: application/json
   
   {
       "to": "+49151237346xx",
       "from": "InfoText",
       "text": "Your confirmation code is 6697",
       "dlrCallbackUrl": "https://my-callback-url/receive-delivery-report"
   }

Receiving notification

For all webhooks events, the payload sent to your callback URL will follow the same structure. Every request will have two objects: event and data. This simplifies the process of using a single endpoint for all callbacks and distinguishing between events that require different handling.

For the request to your webhook to be marked as successful, your endpoint must return HTTP status 200 OK.

If in a short period of time multiple changes triggered an event, the notification to your application could send them in a single request, grouped in the "data"object. There can be up to 200 events informations grouped in the data object, therefore, your endpoint must be able to iterate over the entire object

Example notification

The body of the HTTP request to your callback URL will contain a JSON object like the following:

{
    "event": "dlr_update",
    "data": [
        {
            "campaignId": "14b09fcc-3beb-46ae-b7dc-22b52ffd0bfd",
            "msgId": "d8ca3153-cb30-402b-b97e-ccc4df49fe00",
            "trackData": "",
            "statusCode": 1,
            "status": "DELIVERED",
            "errorCode": null,
            "datetime": "2022-03-03 15:30:24"
        },
        {
            "campaignId": "a710a44a-e784-4199-b73c-a2c8bfd41b59",
            "msgId": "a710a44a-e784-4199-b73c-a2c8bfd41b59",
            "trackData": "2b31bc92-c781-44f3-9fd5-f86e8404bddb",
            "statusCode": 1,
            "status": "DELIVERED",
            "errorCode": null,
            "datetime": "2022-03-03 15:30:24"
        },
        {
            "campaignId": "4dd5e899-6ced-4fd5-bbb6-34e51507e3df",
            "msgId": "4dd5e899-6ced-4fd5-bbb6-34e51507e3df",
            "trackData": "22553dae-6b0e-4fca-a031-80a4e21138d9",
            "statusCode": 1,
            "status": "DELIVERED",
            "errorCode": null,
            "datetime": "2022-03-03 15:30:24"
        }
    ]
}

Because multiple notifications can be sent to your webhook in a single request, they are all put together in an the data as an array of objects

Note: When you send a single SMS, the parameters campaignId and msgId are the same. When you send a bulk SMS campaign, they are different.

Retry policy

If the request to your webhook fails (timeout, maintenance or HTTP 4xx - 5xx), the API will retry it up to 10 times, with an exponential backoff technique. If the request fails after 10 attempts, the notification is discarded and no further requests are attempted.

After the first try, the retry policy will take into account this delay:

List of webhook events

The event parameter can have the following values:

Best practices

When using webhooks, it's important to think about the following:

Respond quickly

Your app has a short period of time to process the request. You should queue information regarding notification changes and then process those requests on a different thread.

Expect simultaneous notifications

In many situations, you might get concurrent notifications in a short amount of time. For example, if you sent a bulk SMS campaign and we receive multiple delivery reports from the carrier, you can receive multiple notifications before you have processed the first notification.