Callbacks (WebHooks)

Callbacks are notifications that you 've asked Routee to send back to you (well, in your web service).

There are two type of callbacks:

Voice Messaging Callbacks##

Voice callbacks are generated when the status of a Voice message is changing. They can be used either when sending only one Voice message or a campaign.

Your callback service will receive a POST HTTP request with the following request body for an individual message progress of the Voice campaign:

  "messageId": "string",
  "campaignTrackingId": "string",
  "to": "string",
  "groups": [
  "campaignName": "string",
  "from": "string",
  "country": "string",
  "applicationName": "string", 
  "price": "number",
  "originatingService": "string",
  "status": {
    "name": "string",
    "updatedDate": "string"
  "direction": "string",
  "audioMessage": {
    "text": "string",
    "language": "string",
    "gender": "string"
  "fileURL": "string",
  "hangupDelay": "number",
  "respectQuietHours": "boolean",
  "duration": "number",
  "createdAt": "date",
  "chargeInterval": "number"
messageIdThe trackingId of the Voice message.
campaignTrackingIdThe trackingId of the campaign.
toThe recipient of the Voice message (in E.164 format).
fromThe senderId of the Voice message.
countryThe country of the recipient.
operatorThe operator of the recipient.
groupsAll contact groups (tags) that this contact belongs to.
campaignNameThe name of the Voice Campaign.
statusThe full status object of the Voice message.
status.nameThe status name of the Voice message.
status.updatedDateThe date of the last status change of the Voice.
applicationNameThe name of the application that was used to send this message.
priceThe cost of the Voice.
directionThe direction of the Voice.
originatingServiceThe service that sent this message.
audioMessage.textThe message that was sent.
audioMessage.genderThe gender of the voice message to be played. VALUES: "male", "female".
audioMessage.languageThe language of the voice message to be played. VALUES: "en-US", "de-DE", "fr-FR", "it-IT", "pt-BR", "es-ES", "es-LA", "en-GB", "el-GR", "bg-BG", "pl-PL", "hu-HU", "sv-SE".
fileURLThe Url that was sent.
hangUpDelayThe time to wait for the call to be answered
respectQuietHoursIndicates if the call should respect the quiet hours, default value: false.
createdAtThe time the message was created.
chargeIntervalThe time interval used for charging this voice message (in seconds).

Voice Campaign Callback##

When used for a voice 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 Voice messages, changes status (OnChange).
Your callback service will receive a POST HTTP request with the following request body:

  "trackingId": "string",
  "name": "string",
  "totalRecipients": "string",
  "campaignStatus": "string",
  "messageStatuses": {
    "Unknown": "string",
    "Queued": "string",
    "Initiated": "string" ,
    "Ringing": "string" ,
    "InProgress": "string" ,
    "Completed": "string",
    "Busy": "string",
    "NoAnswer": "string",
    "Failed": "string" 
  "callbackInfo": {
    "url": "string",
    "strategy": "string"
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 Voice per message status.
callbackInfoDefines the notification callback information for the progress of the bulk send out - campaign
callbackInfo.urlThe URL that will be called when an update occurs
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 a Voice message is changing status (or a percentage in campaign callback).

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

Be careful when you enable Voice 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 Voice message 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

What’s Next