Callbacks (Webhook)

Callbacks are notifications that you 've asked Routee to send back to you when the status of your Failover messages change.

Failover Callbacks

Your callback service will receive a POST HTTP request with the following request body:

 "trackingId": "string",
 "messages": [
     "type": "Viber",
     "to": "string",
     "from": "string",
     "country": "string",
     "ttl": 10,
     "status": {
       "name": "string",
       "reason": { 
         "detailedStatus": "string",
         "description": "string"
       "updatedDate": "string",
       "expireOnDelivery": "boolean",
       "expiredOnDeliveryAt": "string",
     "body": {
       "text": "string",
       "imageURL": "string",
       "viberAction": { 
         "caption": "string",
         "targetUrl": "string"
     "label": "string", 
     "failoverOnStatuses": [  
     "order": 1,
     "inboundUrl": "string", 
     "price": 0.035,
     "createdAt": "string"
     "type": "Sms",
     "part": 1,
     "parts": 2,
     "label": "string", 
     "to": "string",
     "from": "string",
     "country": "string",
     "operator": "string",
     "ttl": 15,
     "status": {
       "name": "string",
       "reason": { 
         "detailedStatus": "string",
         "description": "string"
       "updatedDate": "string"
     "message": "string",
     "price": 0.003,
     "createdAt": "string",
     "order": 2,
     "latency": 27,
     "failoverOnStatuses": [  
 "terminationChannel": "Sms", 
 "status": "Succeeded",
 "totalPrice": 0.038,
 "originatingService": "Failover",
 "applicationId": "",
 "createdAt": "",
 "updatedAt": ""
trackingIdThe tracking Id of the Failover message.
messagesDetails for the Failover message
typeThe type of the flow channel. Supported values: Sms or Viber
toThe recipient of the Failover message.
fromThe senderId of the Failover message.
countryThe country of the recipient
ttlTime range until message expires in minutes (min 1 minute, max 1440 minutes). Default values 10 minutes for Viber messages and 1200 minutes for SMS.)
expireOnDeliveryIf it's set to true then the service will set the status of the Delivered messages to Expired if the TTL value has passed and no Seen status has arrived. (Default value is false)
expiredOnDeliveryAthe time of the seconds that the ttl will expire after the Delivered status.
statusDetails about the status of the message
status.nameThe status name of the Failover message.
status.reasonThe reason of the status. (this information is optional)
status.reason.detailedStatusThe detailed status.
status.reason.descriptionThe description of the detailed status.
status.updatedDateThe date of the last status change of the Failover message.
bodyDetails about the Viber message
body.textThe text of Viber message.
body.imageURLThe url of the image.
body.viberActionDetails for the button used in the Viber message (this information is optional)
body.viberAction.captionThe displayed text on the button.
body.viberAction.targetUrlThe target URL of the Viber action.
labelThe label that was given to the message. (this information is optional)
failoverOnStatusesDefines the status which will trigger the next channel. Values for SMS channel can be: Undelivered, Failed Values for Viber channel can be: Expired, Failed, Undelivered. Values must be comma separated. The statuses are not case-sensitive Default values for SMS: Undelivered, Failed Default values for Viber: Expired, Failed, Undelivered The statuses are not case-sensitive
orderThe order of the specific channel in the Failover sequence
inboundUrlThe defined callback URL that will receive the inbound messages. Check here for details. (this information is optional)
priceThe cost of the message
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.
partThe number of the current SMS part.
partsThe total number of SMS parts.
operatorThe operator of the recipient.
latencyThe overall delivery latency of the message.
terminationChannelThe selected final channel for the communication sequence
statusCodeIn case the status is Failed we give detailed information, the values can be 0 if there is a Server error, 1 if there is Insufficient balance, 2 if there was No next step, 3 if not failover triggered
totalPriceThe total cost including all the channels used
originatingServiceThe service that sent this message.
applicationIdThe id of the application that was used to send this message.

Callback Strategy

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

OnStep: A callback is sent every time the state of the Failover flow changes.

OnCompletion: A callback is sent only when the Failover flow has reached its final status.


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