Callbacks (WebHooks)

Now that we have described the SMS and bulk messaging campaign statuses, we can see how callbacks work. In general, callbacks are notifications that you've asked Routee to send back to you (well, in your web service).

You can check Routee Application Settings to learn how you can set the default Callback URL(s) of your application(s).

There are two type of callbacks:

SMS Callbacks##

SMS callbacks are generated when the status of an SMS is changing, to inform you about the progress of your messages. They can be used either when sending one SMS or a bulk messaging campaign. Each part of a multipart SMS will generate a new payload. Your callback service will receive a POST HTTP request with the following request body:





The trackingId of the SMS (all the parts of a multipart SMS have the same messageId).


The unique id of each SMS part included in a message. If the message is multipart then these values will be different for each part.


The trackingId of the campaign (if the SMS was sent using the /SMS/campaign resource).


The number of the current SMS part.


The total number of SMS parts.


A generic label used for tagging the SMS.


The recipient of the SMS message (in E.164 format).


The senderId of the SMS message.


The country of the recipient.


The operator of the recipient.


All contact groups (tags) that this contact belongs to.


The name of the SMS Campaign (if the SMS was part of a campaign).


The full status object of the SMS message.

The status name of the SMS message.


The date of the last status change of the SMS.


The reason of the status


The detailed status.
Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation, Expired.


The description of the detailed status


The message that was sent.


The name of the application that was used to send this message.


The overall delivery latency of the message.


The cost of the SMS.


The direction of the SMS.


The service that sent this message.

Bulk Messaging Campaign Callback##

When used in a bulk campaign, the callback will be called when the campaign has received a final status (OnCompletion) or every time a total of 10% of the campaign SMSs, changes status (OnChange). Your callback service will receive a POST HTTP request with the following request body:





The trackingId of the campaign


The name of the SMS campaign


The number of recipients that participate in the campaign


The status of the bulk campaign (see above)


Defines the number of SMS per message status. Either Queued, Sent, Failed, Unsent, Delivered or Undelivered.


Defines the notification callback information for the progress of the bulk send out - campaign


The URL that Routee will POST to, each time your bulk send out - campaign status changes to one of the following: Scheduled, Queued, Sent, Running, Finished or Failed


States when the URL will be called.
Choose one of the two options:
on every status change (OnChange)
when a final status arrives (OnCompletion)

Callback Strategy##

For each callback type, you can define the callback strategy:

OnChange: A callback is sent every time an SMS is changing status (or a percentage in campaign callback).

OnCompletion: A callback is sent only when an SMS or a campaign has reached its final status.

Be careful when you enable SMS callbacks for a bulk messaging campaign, especially when you set the callback strategy to be OnChange. Routee will hit your web service every time an individual SMS is changing status. Depending on the number of recipients this will end up in a large amount of requests.


Callback Retry Policy

When Routee POSTs back to your service, an HTTP 200 OK response must be returned within 2 seconds. If Routee doesn't receive a 200 OK response within 2 seconds will drop the connection and will try to POST again (up 12 retries for 24 hours max) with the following retry policy after the initial callback attempt:

1st retry: 30 sec
2nd retry: 1 minute
3rd retry: 2 minutes
4th retry: 5 minutes
5th retry: 10 minutes
6th retry: 15 minutes
7th retry: 30 minutes
8th retry: 1 hour
9th retry: 2 hours
10th retry: 4 hours
11th retry: 8 hours
12th retry: 24 hours


Whitelist IP for callback service

Whitelist all the IPs that resolve to the following domain:
in order to be able to receive callback requests from Routee