Webhooks

Webhooks let your systems receive near real-time notifications for events such as delivery statuses, mobile-originated messages (i.e. replies), short code submissions, and URL clicks.

What are Webhooks

A webhook is an us. Event data contains all the relevant information about what just happened, including the type of event and the data associated with that event. When an event occurs, we make an HTTP request to your endpoint with the event data.

Your application reads the request and takes an action. Some examples include:

• Updating a database record,
• Contacting a customer when they respond positively to a SMS or short code,
• Updating CRM systems,
• Removing a customer from future correspondence if they opt-out,
• Updating customer engagement statistics,
• Calculating ROI on your SMS campaigns

Your endpoint can be written in any language and framework that can serve HTTP. It may accept either a GET request with data in the query string or a POST request with a JSON body.

Webhooks provide an easy and fast way to receive events. Our webhook engine performs an HTTP request to your server as soon as the delivery status, reply, short code interaction or URL click is received. This mechanism removes the latency that is involved with polling for new data.

When to use Webhooks

Many events that occur within your account have synchronous results. These results are immediate and directly respond to an executed request. For example, a successful API request to send an SMS immediately returns a 200 OK response with an EventID. Such requests don’t require webhooks, as the key information is already available.

Other events that occur within your account are asynchronous. These happen at a later time. Most commonly these involve:

• SMS delivery statuses: Events confirming that your SMS was delivered or not.
• Replies to your messages and short codes: Events containing incoming reply/message data from your customers.
• URL previews / click tracking: Events indicating information about customer interactions with URLs in your SMSes.

Webhook Types

The table below summarizes the different webhook types and what their applications are.

Where to Setup Webhooks

Managing webhooks is done exclusively through the Control Panel.

To configure webhooks follow these steps:

1. Navigate to ‘Settings’ on the top right-hand side menu of your control panel, then click ‘Webhooks’.
2. Click the 'Create Webhook' drop down button in the top-right hand side of the screen to create a new webhook. This will open a modal that provides inputs to create the webhook.

Get started in three steps

1. Create a webhook endpoint on your server.
   • Methods: GET and POST are supported. Other HTTP methods are not supported. See Allowed Methods, URLs, and Headers.
   • Transport: HTTPS is required for production use.
   • Sizes: URL length and request body sizes are limited. See Allowed Methods, URLs, and Headers.
2. Use the built-in tools in the Control Panel to validate URLs and JSON and to test the full path to your server. See _Webhook Testing and Validation _.
3. Save your endpoints and use the incoming data for your own applications.
   • Responses: Always return an HTTP 2xx response, to prevent retries.

Conventions used in these pages

Some conventions used throughout the webhook integration are discussed in the table below.