This guide explains how to use webhooks as an efficient alternative to polling for receiving message replies and delivery reports. Instead of making constant requests to API endpoints, you can configure webhooks to have Sinch MessageMedia automatically send this information to your application as the events happen. This article will walk you through the essential steps to manage your webhooks, including how to create, retrieve, update, and delete them, allowing you to easily incorporate real-time, two-way messaging into your system.
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.