Callbacks (Webhook)

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

Failover Callbacks

Your callback service will receive a POST HTTP request with a JSON body. Example:

{
"trackingId": "30830fad-21ed-49b0-89d0-bbada2fd5640",
"messages": [
{
"type": "Viber",
"trackingId": "0a047b46-a4dd-4ca8-b817-a6a134dd1234",
"to": "+306912345678",
"from": "Routeetest",
"country": "GR",
"ttl": 10,
"expireOnDelivery": false,
"expiredOnDeliveryAt": null,
"status": {
"name": "DELIVERED",
"reason": {
"detailedStatus": "Delivered",
"description": "The message was delivered to its recipient."
},
"updatedDate": "2019-07-05T10:28:44.996Z"
},
"body": {
"text": "This is a test, please ignore!",
"imageUrl": "https://example.com/image.png",
"action": {
"caption": "Go",
"targetUrl": "https://www.routee.net/"
}
},
"label": "labelName",
"failoverOnStatuses": ["EXPIRED", "FAILED", "UNDELIVERED"],
"order": 1,
"inboundUrl": "https://your-server.com/inbound",
"price": 0.035,
"createdAt": "2019-07-05T10:28:44.566Z"
},
{
"type": "Sms",
"messageId": "82a91dc3-e842-41eb-86e5-07d55eb51234",
"smsId": "1274d238-38b7-4c56-b49a-9b70d25c1234",
"to": "+306912345678",
"from": "Routee",
"country": "GR",
"operator": "Vodafone",
"ttl": 15,
"status": {
"name": "Delivered",
"reason": {
"detailedStatus": "Delivered",
"description": "The SMS was sent and it was delivered to its recipient."
},
"updatedDate": "2019-07-05T10:28:49Z"
},
"body": "Hello from failover",
"price": 0.036,
"label": "labelName",
"order": 2,
"part": 1,
"parts": 1,
"latency": 4,
"failoverOnStatuses": ["Undelivered", "Failed"],
"createdAt": "2019-07-05T10:28:45.227Z"
}
],
"terminationChannel": "Sms",
"status": "Succeeded",
"statusCode": null,
"totalPrice": 0.036,
"originatingService": "Failover",
"applicationId": "5b223c27e4b04b9cdaa71234",
"createdAt": "2019-07-05T10:28:44.44Z",
"updatedAt": "2019-07-05T10:28:49.634Z"
}

Notes on the example:

Viber: expireOnDelivery and expiredOnDeliveryAt are on the message object (not inside status). The button is under body.action (not body.viberAction). SMS text is in body (not message).
statusCode is only present when the root status is "Failed"; then it is one of the strings "0", "1", "2", "3".

Callback payload — parameter reference

KEY	DESCRIPTION
Root level
trackingId	The tracking id of the Failover flow.
messages	Array of message objects (one per step). Each object has type Sms, Viber, or Voice.
terminationChannel	The channel that ended the flow. Values: Sms, Viber, Voice.
status	Overall flow status. Values: Queued, InProgress, Succeeded, Failed.
statusCode	Present only when status is Failed. String: "0" Server error, "1" Insufficient balance, "2" No next step, "3" Not failover triggered.
totalPrice	Total cost of the flow.
originatingService	The service that sent the flow (e.g. Failover).
applicationId	The application id used for the flow.
createdAt	When the flow was created (ISO 8601).
updatedAt	When the flow was last updated (ISO 8601).
Per message (all types)
type	Channel type. Values: Sms, Viber, Voice.
to	The recipient.
from	Sender id (SMS) or sender name (Viber).
country	Recipient country (ISO 3166-1 alpha-2).
ttl	TTL in minutes. Viber: 0.5–1440 (default 10). SMS: 1–1440 (default 1200).
status	Message delivery status.
status.name	Status name (e.g. Delivered, Undelivered, Failed for SMS; DELIVERED, EXPIRED, FAILED for Viber).
status.reason	Optional reason details.
status.reason.detailedStatus	Detailed status.
status.reason.description	Human-readable description.
status.updatedDate	Date of the last status change (ISO 8601).
label	Optional label for the message.
failoverOnStatuses	Array of status strings that trigger the next channel. Case-insensitive. Defaults: SMS — Undelivered, Failed; Viber — Expired, Failed, Undelivered; Voice — Busy, NoAnswer.
order	The order of this step in the Failover sequence.
price	The cost of this message.
createdAt	When this message was created (ISO 8601).
Viber only
trackingId	Tracking id of this Viber message.
expireOnDelivery	If true, the messaging provider may set Delivered messages to Expired after TTL if no Seen status is received. Default: false.
expiredOnDeliveryAt	ISO 8601 date/time when the message was expired after delivery. Present only when expireOnDelivery was true and the message has expired.
body	Object with message content.
body.text	The text of the Viber message.
body.imageUrl	The image URL.
body.action	Optional button/action.
body.action.caption	Button text (1–30 characters).
body.action.targetUrl	Button URL.
inboundUrl	Callback URL for inbound messages. Optional. See Viber inbound messages docs.
SMS only
body	The SMS text (string).
messageId	Id of the SMS message (same for all parts of a multipart SMS).
smsId	Unique id of this SMS part.
part	Current part number (multipart).
parts	Total number of parts (multipart).
operator	The operator of the recipient.
latency	Overall delivery latency (ms).

Callback strategy

You can choose when callbacks are sent:

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 a final status (Succeeded or Failed).

Callback retry policy

Your endpoint must respond with HTTP 200 OK within 2 seconds. If Routee does not receive 200 OK within 2 seconds, it will close the connection and retry up to 12 times over 24 hours, with the following delays after the initial attempt:

Retry	Delay
1st	30 sec
2nd	1 min
3rd	2 min
4th	5 min
5th	10 min
6th	15 min
7th	30 min
8th	1 hour
9th	2 hours
10th	4 hours
11th	8 hours
12th	24 hours

Whitelist IP for callback service

To receive callbacks from Routee, whitelist all IPs that resolve from:

callbacksallow.routee.net