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:

messageIdThe trackingId of the SMS (all the parts of a multipart SMS have the same messageId).
smsIdThe unique id of each SMS part included in a message. If the message is multipart then these values will be different for each part.
campaignTrackingIdThe trackingId of the campaign (if the SMS was sent using the /SMS/campaign resource).
partThe number of the current SMS part.
partsThe total number of SMS parts.
labelA generic label used for tagging the SMS.
toThe recipient of the SMS message (in E.164 format).
fromThe senderId of the SMS message.
countryThe country of the recipient.
operatorThe operator of the recipient.
groupsAll contact groups (tags) that this contact belongs to.
campaignNameThe name of the SMS Campaign (if the SMS was part of a campaign).
statusThe full status object of the SMS message.
status.nameThe status name of the SMS message.
status.updatedDateThe date of the last status change of the SMS.
status.reasonThe reason of the status
status.reason.detailedStatusThe detailed status.
Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation, Expired.
status.reason.descriptionThe description of the detailed status
messageThe message that was sent.
applicationNameThe name of the application that was used to send this message.
latencyThe overall delivery latency of the message.
priceThe cost of the SMS.
directionThe direction of the SMS.
originatingServiceThe 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:

trackingIdThe trackingId of the campaign
nameThe name of the SMS campaign
totalRecipientsThe number of recipients that participate in the campaign
campaignStatusThe status of the bulk campaign (see above)
messageStatusesDefines the number of SMS per message status. Either Queued, Sent, Failed, Unsent, Delivered or Undelivered.
callbackInfoDefines the notification callback information for the progress of the bulk send out - campaign
callbackInfo.urlThe 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
callbackInfo.strategyStates 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