Callbacks (WebHooks)

Now that we have described the SMS and bulk messaging campaign statuses, we can see how callbacks work. In general, callbacks are notifications that you've asked Routee to send back to you (well, in your web service).

You can check Routee Application Settings to learn how you can set the default Callback URL(s) of your application(s).

There are two type of callbacks:

SMS Callbacks

SMS callbacks are generated when the status of an SMS is changing, to inform you about the progress of your messages. They can be used either when sending one SMS or a bulk messaging campaign. Each part of a multipart SMS will generate a new payload. Your callback service will receive a POST HTTP request with the following request body:

{
   "messageId":"string",
   "smsId":"string",
   "campaignTrackingId":"string",
   "part":"number",
   "parts":"number",
   "label":"string",
   "to":"string",
   "from":"string",
   "country":"string",
   "operator":"string",
   "groups":[
      "string"
   ],
   "campaignName":"string",
   "status":{
      "name":"string",
      "reason":{
         "detailedStatus":"string",
         "description":"string"
      },
      "updatedDate":"string"
   },
   "message":"string",
   "applicationName":"string",
   "latency":"number",
   "price":"number",
   "direction":"string",
   "originatingService":"string"
}

KEY	DESCRIPTION
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.
campaignTrackingId	The trackingId of the campaign (if the SMS was sent using the /SMS/campaign resource).
part	The number of the current SMS part.
parts	The total number of SMS parts.
label	A generic label used for tagging the SMS.
to	The recipient of the SMS message (in E.164 format).
from	The senderId of the SMS 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 SMS Campaign (if the SMS was part of a campaign).
status	The full status object of the SMS message.
status.name	The status name of the SMS message.
status.updatedDate	The date of the last status change of the SMS.
status.reason	The reason of the status
status.reason.detailedStatus	The detailed status. Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation, Expired.
status.reason.description	The description of the detailed status
message	The message that was sent.
applicationName	The name of the application that was used to send this message.
latency	The overall delivery latency of the message.
price	The cost of the SMS.
direction	The direction of the SMS.
originatingService	The service that sent this message.

Bulk Messaging Campaign Callback

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

{
   "trackingId":"string",
   "name":"string",
   "totalRecipients":"number",
   "campaignStatus":"string",
   "messageStatuses":{
      "string":"number"
   },
   "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 SMS per message status. Either Queued, Sent, Failed, Unsent, Delivered or Undelivered.
callbackInfo	Defines the notification callback information for the progress of the bulk send out - campaign
callbackInfo.url	The URL that Routee will POST to, each time your bulk send out - campaign status changes to one of the following: Scheduled, Queued, Sent, Running, Finished or Failed
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 SMS changes status. For campaigns, also fires on each 10% progress milestone.
OnCompletion	Only when an SMS 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.

Updated about 1 month ago

What’s Next

Other Messaging Concepts