Getting Started

The first step to adding webhooks to your account integration is to build your own custom endpoint. Creating a webhook endpoint on your server is no different from creating any page on your website.

Before looking at the code, there are two different versions of webhooks. To learn more about each webhook type and the variables available, and how to set them up with your application, please see below.

Protocol Support.

Webhook endpoints can be added, edited, assigned and deleted in the Control Panel by navigating to ‘Settings’ on the top right-hand side menu of your control panel and selecting 'Webhooks'.

Return a 2xx status code quickly

To acknowledge receipt of an event, your endpoint must return a 2xx HTTP status code to us. All response codes outside this range, including 3xx codes, indicate to us that you did not receive the event.

If we does not receive a 2xx HTTP status code, the notification is retried. After 5 failures to send the notification, we mark the event as failed and stops trying to send it to your endpoint.

Because properly acknowledging receipt of the webhook notification is so important, your endpoint should return a 2xx HTTP status code prior to any complex logic that could cause a timeout.

Test Webhooks

Test that your webhook endpoint is working properly before taking it live.

As your webhook endpoint is used asynchronously, its failures may not be obvious to you until it’s too late. Always test that your endpoint works:

• Upon initial creation
• After taking it live
• After making any changes

Webhook Testing provides a means to debug your configuration and application. There are two ways to test your webhook endpoint:

Both options require registering your endpoint(s) on your account, which you will need to do before going live anyway. You may experience firewall or tunneling issues when testing, particularly when developing on localhost so be sure to check out the Webhooks best practices section.

Testing from the Control Panel

To test your webhook endpoint using the Control Panel:

The results of the test and your endpoint’s response will be displayed on screen. Do note that these are fake events with fake IDs. They do not contain real, actionable data.

Troubleshooting

Please always ensure the following:

• The webhook URL specified is correct, the domain is registered, and it resolves to an IP address.
• The IP addresses from which we will perform HTTP posts are whitelisted on your firewall and that the relevant ports are open.
• The web server has been configured to host your application.
• The web server has been configured to allow HTTP posts.
• You are responding with HTTP 200 to our inbound requests.

After building, testing, and deploying your webhooks to production, set up the necessary endpoints so we know where to send live mode events.

Go Live - Webhooks

Complete your tested webhooks integration by enabling it on production.

Creating and assigning webhook endpoints in your account

Webhook endpoints can be added, edited, assigned and deleted in the Control Panel.

We supports 4 different endpoint types.

• Delivery Statuses (DLRs)

• Replies (MOs)

• Short Code Replies

• URL Tracking

Once you have created your webhook, tested and saved it, a pop-up module will appear prompting you to assign your newly created webhook to your desired sending channels, URLs or Short Codes.

You can edit existing webhooks by clicking the 3 dots in the 'Actions' column and selecting 'Assign To' to bulk assign your webhook.

Managing your existing webhook endpoints

Website Sending

If you are sending SMS from the website and want to receive updates via webhooks, you can assign webhooks on the ‘My Settings’ page using the following quick links or by follow these steps:

• Delivery Statuses (DLRs) - This endpoint can be added on the My Settings page under the Forwarding Tab.

• Replies (MOs) - This endpoint can be added on the My Settings page under the Forwarding Tab.

Navigate to ‘Settings’ on the top right-hand side menu of your control panel and click ‘Profile Settings’. Select the ‘Forwarding’ tab and click on the relevant DLR and/or MO drop-down menu to select the desired webhook endpoint. Once you have made your selection click ‘Update Settings’ to save your changes.

Sending via an API

If you are sending SMS through an API channel, you can assign your webhooks on the API Keys page.
To assign your endpoint to the DLR and/or MO functions in your API channel:

• Navigate to ‘Settings’ on the top right-hand side menu of your control panel, then click ‘API Keys’.
• Click the 3 dots in the ‘Actions’ column on the right-hand side of the API channel you wish to assign the webhook endpoints to and select 'Settings'.
• Select the ‘Webhooks’ tab and click on the relevant DLR and/or MO drop-down menu to select the desired webhook endpoint.
• Click ‘Update Settings’ to save your changes.

Short Codes

• Short Code Replies - This endpoint is added per short code on the Short Codes > Setup page.

Navigate to ‘Short Codes’ on the left-hand side menu of your control panel and click ‘Setup’. Click the ‘3 dots’ under the action column on the right-hands side for either your dedicated Short Code or Keyword and select 'Forwarding'. On this menu select the desired webhook endpoint. Once you have made your selection click ‘Save’ to save your changes.

URL Shortening and Landing Pages

• URL Tracking - This endpoint is added per URL on the URL Shortening page by clicking the Edit button and then selecting your desired webhook endpoint.

• Landing Pages - This endpoint is added per Landing Page on the Landing Pages page by clicking the Edit button and selecting your desired Webhook endpoint on the 'Page Setting' menu on the right-hand side.