How to use Sinch MessageMedia Webhooks

If you are looking to incorporate 2 way messaging into your application, or find out information about the status of your sent messages, one option is to make requests to the replies and delivery reports endpoints. However, this is not suitable or efficient in many cases and the alternative is to set up webhooks so that MessageMedia send you replies and delivery report information as those events occur. 

This guide will cover:

• Creating a webhook
• Retrieve a webhook
• Updated a webhook
• Delete a webhook

Prerequisites

In order to work through this tutorial, you need:

• MessageMedia API Key

This guide uses CURL to demonstrate webhooks management. However, you can apply these concepts in any language using the documentation or any of the SDKs. CURL commands can be entered into a Command Line Interface.

Creating a webhook

To create a webhook that will be triggered when an SMS is received, make the following call and substitute in your API Key and Secret: 

curl -X POST \
  --url 'https://api.messagemedia.com/v1/webhooks/messages' \
  -u 'BasicAuthUserName:BasicAuthPassword' \
  -H 'Content-type: application/json' \
  --data-raw '{
  "url": "http://webhook.com",
  "method": "POST",
  "encoding": "JSON",
  "headers": {
    "Account": "Developer7000"
  },
  "events": [
    "RECEIVED_SMS"
  ],
  "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}"
}'

This is what a successful response body should look like.

{"url":"http://webhook.com","method":"POST","id":"4dcb0f96-1617-47bb-bcea-7337fac89a12","encoding":"JSON","events":["RECEIVED_SMS"],"headers":{"Account":"DeveloperPortal7000"},"template":"{\"id\":\"$mtId\",\"status\":\"$statusCode\"}"}

Retrieving all webhooks

We can find out all the details of the previously created webhooks by making a GET request to the same endpoint. In CURL, remembering to substitute your API Key and Secret, this command looks like: 

curl -X GET -G \
  --url 'https://api.messagemedia.com/v1/webhooks/messages' \
  -u 'BasicAuthUserName:BasicAuthPassword'

And a successful response for this request should look like this.

{"page":0,"pageSize":100,"pageData":[{"url":"http://webhook.com","method":"POST","id":"4dcb0f96-1617-47bb-bcea-7337fac89a12","encoding":"JSON","events":["RECEIVED_SMS"],"headers":{"Account":"DeveloperPortal7000"},"template":"{\"id\":\"$mtId\",\"status\":\"$statusCode\"}"}...]}

Updating a webhook

To update a webhook, you’ll need the id of the webhook. You can retrieve this by looking at the response of the above example which should display the id of each webhook along with other details. In the following call, we will update the URL of the webhook to point to a different location. This is useful if you want to test your webhook, for example, by pointing it to a webhook interceptor:

curl -X PATCH \
  --url 'https://api.messagemedia.com/v1/webhooks/messages/4dcb0f96-1617-47bb-bcea-7337fac89a12' \
  -u 'BasicAuthUserName:BasicAuthPassWord' \
  -H 'Content-type: application/json' \
  --data-raw '{
  "url": "https://myurl.com",
  "method": "POST",
  "encoding": "FORM_ENCODED",
  "events": [
    "RECEIVED_SMS"
  ],
  "template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}"
}'

A successful call to this endpoint will gain return the details of the endpoint, so you can check it has been updated as intended:

{"url":"https://myurl.com","method":"POST","id":"4dcb0f96-1617-47bb-bcea-7337fac89a12","encoding":"FORM_ENCODED","events":["RECEIVED_SMS"],"headers":{},"template":"{\"id\":\"$mtId\", \"status\":\"$statusCode\"}"}

Delete a webhook

Similar to the updating a webhook, you’ll need an id to be able to delete a webhook. The following call will delete the webhook: 

curl -X DELETE \
  --url 'https://api.messagemedia.com/v1/webhooks/messages/4dcb0f96-1617-47bb-bcea-7337fac89a12' \
  -u 'BasicAuthUserName:BasicAuthPassword'

And a successful response should output null in the command line, but with a 200 level response code.

Conclusion

The above four calls are all you will need to manage webhooks for the MessageMedia API.  

Resources

• Webhooks API documentation