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##

For each callback type, you can define the callback strategy:

OnChange: A callback is sent every time an SMS is changing status (or a percentage in campaign callback).

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

Be careful when you enable SMS 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 SMS 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:
callbacksallow.routee.net
in order to be able to receive callback requests from Routee

Callbacks (WebHooks)

SMS Callbacks##

Bulk Messaging Campaign Callback##

Callback Strategy##

👍
Callback Retry Policy

🚧
Whitelist IP for callback service

SMS Callbacks##

Bulk Messaging Campaign Callback##

Callback Strategy##

👍Callback Retry Policy

🚧Whitelist IP for callback service

👍
Callback Retry Policy

🚧
Whitelist IP for callback service