Create a webhook

A webhook is an URL that you can register when you want the BulkSMS system to notify you about your messages. You can register multiple webhooks, and each one will be called. (Note: you can also use our Web App to manage your webhooks interactively.)
If you want to be notified of SENT messages and RECEIVED messages you need to create two webhooks.

Implementing your webhook

Code samples of Webhook implementations:

• PHP

When you implement your webhook, there are a few rules to be aware of:

• Your webhook must process POST requests that contains an array of messages in the post body. This input given to your webhook has the same structure as the output produced when you call Retrieve Messages.
• When you register or update your webhook, the URL will be tested by invoking it with an empty array ([]).
• It is possible for your webhook to receive multiple updates for the same message and status. It happens from time to time that the mobile network duplicates status updates.
• The order by which the webhook is invoked can be unexpected. For example, if sender A replies before sender B, your webhook might get the reply from B first.
• The webhook is expected to comply with good practices with regard to the status code it responds with.
  • A status code in the 1xx and 2xx range is taken as an acknowledgement that the invocation was received and that the webhook host is ready to receive another.
  • A status code in the 4xx range is taken as a permanent problem and indicates that the webhook cannot process the message. The specific message that caused the error will be discarded, but your webhook will be invoked again when another message becomes available.
  • Any other status code will be taken as a temporary problem; and indicates that the BulkSMS system should retry. The specific message that caused the error will not be discarded and your webhook will be invoked again with this message (see the subsequent section for more details on retry processing).
• Your webhook has to respond within 30 seconds. If no response is given in this time, the invocation will be retried.
• It is good idea to add a secret to your URL in order to make it more secure. Here is an example: https://www.example.com/hook.php?secret=pass763265word
• You can use a non-standard port if necessary, for example: https://www.example.com:8321/hook.php?secret=pass763265word
• Your webhook can be called from a dynamic range of IP addresses, and you should be prepared to accept that the source IP can change in the future, without notice. This practice has become common with cloud-hosted solutions. If this is an insurmountable problem for your organisation, please contact support.

Testing and troubleshooting

Use curl to test your webhook. The command below is a template that shows how the BulkSMS system invokes your code. It must return 200 for your URL before you can register it as a webhook.

curl -i -X POST 'YOUR_URL_HERE' --header 'Content-Type: application/json' --header 'User-Agent: BulkSMS Invoker' --data-raw '[]'

When a 200 is returned for an empty array, modify the template to post multiple messages by adding JSON between the square brackets ('[]').

After your webhook is successfully registered, you can send a message to 1111111 for an end-to-end test. The delivery to this test number will fail, but your webhook will be invoked (and there are no charges).

The retry process

The process the BulkSMS systems follow to handle retries is roughly the following:

• The first retry is scheduled for 90 seconds into the future.
• After the first retry, subsequent failures will have longer delays, following this sequence - 3 minutes, 6 minutes, 12 minutes thereafter the message will be retried every 15 minutes for a 2 day period.
• When all retries fail, the message will be discarded.

Problem reports via email

Your are strongly advised to provide an email address when you register your webhook. A notice will be sent to this email address to keep you in the loop whenever there are problems with your webhook. In order to prevent your inbox from being flooded, the system sends a notice about an observed error no more than once in a 24 hour period.

The following emails can be expected

• A message retrying email is sent after an invocation has failed with a retry-able error. This email is an early warning, allowing you to investigate your systems.
• A message discarded email is sent after failure email is send when a message is discarded as a consequence of a non-retry-able error.

{
  "name": "My MT Webhook",
  "url": "https://www.example.com",
  "contactEmailAddress": "tech_team@example.com",
  "triggerScope": "SENT",
  "invokeOption": "MANY",
  "active": true,
  "onWebApp": true
}

{
  "id": 234,
  "name": "My MT Webhook",
  "url": "https://www.example.com",
  "contactEmailAddress": "tech_team@example.com",
  "triggerScope": "SENT",
  "active": true,
  "onWebApp": true
}