Share article:

• 
• 
• 
• 

Introducing MessageMedia Webhooks Management API

Developers 5 min read | wrote in blog on May 31, 2018

Back in the day, developers would write code that hits an API every few minutes to check for changes. This concept is known as polling and it’s quite simple. You send a request to an endpoint to check for new events at a set frequency and wait for it to respond. If it doesn’t, then there are no new events to share. You can already tell some of the drawbacks of this approach. For starters, there’s no guarantee that data will be returned at every request and if there is data, it might not be up-to-date as it could’ve been produced way before you even made the request. In addition to this, the server providing the endpoint will be under a lot of stress if you’re making frequent calls it.

Then came in webhooks and the world of event management was never the same again. Like polling, webhooks provide your application with a way of consuming new event data from an endpoint. Further, webhooks are a lot smarter and nicer. Instead of sending multiple requests for new events, your application will monitor the endpoint URL and whenever a new event occurs, it POSTs the event data to the specified URL, updating the application in real-time. The main difference between polling and webhooks is that, while polling makes calls without knowing whether the endpoint has any data ready, webhooks receive calls through HTTP POST requests from the endpoint only when it has data updates.

MessageMedia Webhooks Management API works in a similar fashion. For instance, when an SMS is received or a message has failed to deliver, a webhook can notify you of this event by POSTing a user-defined payload containing the details of the event such as service type, message ID and message timestamp to the URL of your choice. With the Webhooks Management API, you can create a webhook to receive real-time notifications, retrieve a list of all the previously created webhooks, update a webhook or even delete one.

A typical webhook would have the following structure:

{
  "url": "http://webhook.com",
  "method": "POST",
  "encoding": "JSON",
  "headers": {
    "Authentication": "Basic V2p234DSYmpOSEhQbUxRQzVJD886cHNoMWVjM2dadkR2M21493LVNTJvWHkxdEdl9XBu"
  },
  "events": [
    "RECEIVED_SMS"
  ],
  "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}"
}

The “template” field is what the returned payload is going to look like. This means you have full control over what data is returned. You can add as many fields as you like to your template. For instance, Message ID would be $mtId, Account ID would be $accountId and if you’d like the destination address returned, you can use $destinationAddress. In addition to this, you can choose what sort of event will trigger the webhook, whether’s it will be a received SMS, an enroute SMS or some other event. View the full list over here.

You can deliver the webhooks using different content types. You can choose between JSON, XML and FORM_ENCODED.

• "encoding": "JSON" will create the application/json content type header which delivers the JSON payload directly as the body of the POST.
• "encoding": "XML" will create the application/xml content type header which delivers the XML payload directly as the body of the POST.
• "encoding": "FORM_ENCODED" will create the application/x-www-form-urlencoded content type header which sends the JSON payload as a form parameter.

You can choose the one that best fits your needs.

You can select the method type as well. Here’s an example of what a GET request could look like:

{
  "url": "http://webhook.com?messageId=$mtId&status=$statusCode",
  "method": "GET",
  "encoding": "FORM_ENCODED",
  "events": [
    "RECEIVED_SMS"
  ]
}

You must use JSON when sending a request but you get to decide what format the data is returned in. The response can be sent back in a variety of formats including XML, JSON or as a form parameter.

Here are examples of how you can create a webhook and the corresponding payload that will be returned for each one when the webhook is triggered:

Example Request 1

{
  "url": "http://webhook.com",
  "method": "POST", 
  "encoding": "JSON", 
  "events": ["ENROUTE_DR"], 
  "template":"{ 
    \"source_number\":\"$sourceAddress\", 
    \"destination_number\":\"$destinationAddress\",  
    \"message_timestamp\":\"$submittedTimestamp\", 
    \"content\":\"$messageContent\"}" 
}

Returned Payload

{   
  "source_number": "+61456755090",   
  "destination_number": "+61400406401",   
  "message_timestamp": "2018-05-16T00:31:50.214Z",   
  "content": "Hello" 
}

Example Request 2

{
  "url": "http://webhook.com", 
  "method": "POST", 
  "encoding": "XML", 
  "events": ["ENROUTE_DR"], 
  "template":"
     <message_id>$messageId</message_id>, 
     <message_status>$status</message_status>, 
     <status_code>$statusCode</status_code>, 
     <delivery_report_id>$reportId</delivery_report_id>, 
     <message_timestamp>$submittedTimestamp</message_timeatamp>" 
}

Returned Payload

<messageId>4cda321e-5evr-3d26-beas-c3eb60e3ed39</messageId> 
<message_status>enroute</message_status> 
<status_code>202</status_code> 
<delivery_report_id>ab4fd42d-3423-4ew3-821e-fes5aeds4364</delivery_report_id> 
<message_timestamp>2018-05-16T00:31:50.214Z</message_timestamp>

For a more detailed, step by step guide on how you can use each functionality of the Webhooks Management API, check out the webhooks tutorial here.