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": [
    "string"
  ],
  "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"
}

KEY	DESCRIPTION
messageId	The trackingId of the Voice message.
campaignTrackingId	The trackingId of the campaign.
to	The recipient of the Voice message (in E.164 format).
from	The senderId of the Voice message.
country	The country of the recipient.
operator	The operator of the recipient.
groups	All contact groups (tags) that this contact belongs to.
campaignName	The name of the Voice Campaign.
status	The full status object of the Voice message.
status.name	The status name of the Voice message.
status.updatedDate	The date of the last status change of the Voice.
applicationName	The name of the application that was used to send this message.
price	The cost of the Voice.
direction	The direction of the Voice.
originatingService	The service that sent this message.
audioMessage.text	The message that was sent.
audioMessage.gender	The gender of the voice message to be played. VALUES: "male", "female".
audioMessage.language	The 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".
fileURL	The Url that was sent.
hangUpDelay	The time to wait for the call to be answered
respectQuietHours	Indicates if the call should respect the quiet hours, default value: false.
createdAt	The time the message was created.
chargeInterval	The 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"
  }
}

KEY	DESCRIPTION
trackingId	The trackingId of the campaign
name	The name of the SMS campaign
totalRecipients	The number of recipients that participate in the campaign
campaignStatus	The status of the bulk campaign (see above)
messageStatuses	Defines the number of Voice per message status.
callbackInfo	Defines the notification callback information for the progress of the bulk send out - campaign
callbackInfo.url	The URL that will be called when an update occurs
callbackInfo.strategy	States when the URL will be called. Choose one of the two options: on every status change (OnChange) or when a final status arrives (OnCompletion)

Callback strategy

Choose when Routee POSTs to your URL:

Strategy	When callbacks fire
OnChange	Every time an individual Voice message changes status. For campaigns, also fires on each 10% progress milestone.
OnCompletion	Only when an Voice message or campaign reaches a final status.

High volume warning — OnChange on large bulk campaigns generates one request per status change per recipient. Prefer OnCompletion unless you need per-message updates.

Callback retry policy

Your endpoint must respond with HTTP 200 OK within 2 seconds. Otherwise Routee closes the connection and retries (up to 12 attempts over 24 hours).

Attempt	Delay after previous try
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

Design your handler to be idempotent — the same event may be delivered more than once.

Secure your endpoint — Serve callbacks over HTTPS and include a hard-to-guess secret in the callback URL path or query string. Validate it on every request.

Voice Messaging Callbacks

Voice Campaign Callback

Callback strategy

Callback retry policy

What’s Next