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",
     "trackingId":"string",
     "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": [  
            "EXPIRED",
            "FAILED",
            "UNDELIVERED"
         ],
     "order": 1,
     "inboundUrl": "string", 
     "price": 0.035,
     "createdAt": "string"
   },
   {
     "type": "Sms",
     "messageId":"string",
     "smsId":"string",
     "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": [  
            "Failed",
            "Undelivered"
         ]
   }
 ],
 "terminationChannel": "Sms", 
 "status": "Succeeded",
 "statusCode":"",
 "totalPrice": 0.038,
 "originatingService": "Failover",
 "applicationId": "",
 "createdAt": "",
 "updatedAt": ""
}

KEY

DESCRIPTION

trackingId

The tracking Id of the Failover message.

messages

Details for the Failover message

type

The type of the flow channel. Supported values: Sms or Viber

to

The recipient of the Failover message.

from

The senderId of the Failover message.

country

The country of the recipient

ttl

Time range until message expires in minutes (min 1 minute, max 1440 minutes). Default values 10 minutes for Viber messages and 1200 minutes for SMS.)

expireOnDelivery

If 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)

expiredOnDeliveryAt

he time of the seconds that the ttl will expire after the Delivered status.

status

Details about the status of the message

status.name

The status name of the Failover message.

status.reason

The reason of the status. (this information is optional)

status.reason.detailedStatus

The detailed status.

status.reason.description

The description of the detailed status.

status.updatedDate

The date of the last status change of the Failover message.

body

Details about the Viber message

body.text

The text of Viber message.

body.imageURL

The url of the image.

body.viberAction

Details for the button used in the Viber message (this information is optional)

body.viberAction.caption

The displayed text on the button.

body.viberAction.targetUrl

The target URL of the Viber action.

label

The label that was given to the message. (this information is optional)

failoverOnStatuses

Defines 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

order

The order of the specific channel in the Failover sequence

inboundUrl

The defined callback URL that will receive the inbound messages. Check here for details. (this information is optional)

price

The cost of the message

messageId

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

smsId

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.

part

The number of the current SMS part.

parts

The total number of SMS parts.

operator

The operator of the recipient.

latency

The overall delivery latency of the message.

terminationChannel

The selected final channel for the communication sequence

statusCode

In 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

totalPrice

The total cost including all the channels used

originatingService

The service that sent this message.

applicationId

The 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:
callbacksallow.routee.net
in order to be able to receive callback requests from Routee