Webhooks (or Callback URLs)


  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:

Retry attempt Delay
1 1 minute
2 2 minutes
3 5 minutes
4 10 minutes
5 30 minutes
6 1 hour
7 2 hours
8 4 hours
9 8 hours
10 24 hours

List of webhook events

The event parameter can have the following values:

Event Trigger API Reference
(payload example)
dlr_update When a delivery report for a sent SMS is received from the carrier. DLR update
receive_sms When a new SMS is received on your short code or virtual long number. Receive SMS
receive_viber When a new Viber message is received. Receive Viber
receive_whatsapp When a new Whatsapp message is received. Receive Whatsapp
shortlink_hit When a user clicks on a short link from your text message. Shortlink hit
shortlink_hit_update When new details about a visitor of a shortlink becomes available (eg. geolocation). Shortlink hit update
attachment_hit When a user clicks on an attachment link in your text message. Attachment hit
attachment_hit_update When new information about a visitor becomes available (eg. geolocation). Attachment hit update
new_optout When a user is opting out from your marketing campaigns. Contact optout
otp_update When a One-time-PIN is verified. OTP status update
number_lookup When the result of a number carrier lookup is ready. Number lookup

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.

Was this page helpful?