Transaction Callback Service

This page explains how to set up and use a Transaction Callback Service to receive status updates about your requests to some Telesign services. This architecture is only supported for the Messaging, SMS, SMS Verify API, Voice, Voice Verify API, and Inbound SMS products.

Use cases

Once you have set up a Transaction Callback Service, these are examples of when you’ll receive callback notifications:

• When a transaction completes.
• When Telesign determines the final status of the transaction (refer to All status and error codes for a list of status codes that may be returned).
• When receiving events from Telesign Voice.

Key features

• Controlled by you: This is a web service that you set up and control.
• Compound queries: A Transaction Callback Service notification can be used to learn the status of multiple transactions at the same time, unlike an API request to get status.
• Efficient: Makes more efficient use of network system resources (for example, bandwidth or server load) when making compound queries. This may be a significant advantage if you have a high volume of transactions.

Service setup

General requirements

• Base URL: Any URL that you control.
• Protocols: https
• Ports: 443 (The default standard port for HTTPS)
• Authentication: Authentication is optional, but recommended. See Authenticate callbacks for more details.
• Accepts: application/json
• Responds With: application/json

Schema

Note that the schema for a callback varies depending on which Telesign service it comes from. Below is the general schema. The documentation for each product explains any variations from this schema.

Example notification

Note that the verify package in this example is product-specific and not part of the general schema.

Example Callback Notification

POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{ 
  "status": { 
     "updated_on": "2016-07-08T20:52:46.417428Z", 
     "code": 200,
     description": "Delivered to handset" 
   }, 
   "submit_timestamp": "2016-07-08T20:52:41.203000Z", 
   "errors": [], 
   "verify": { 
     "code_state": "VALID", 
     "code_entered": null 
   }, 
   "sub_resource": "sms", 
   "reference_id": "2557312299CC1304904080F4BE17BFB4" 
}

Steps

1. Create a web service with a private URL for receiving callback notifications from Telesign. Notifications are sent as web requests to this service.

   📘

   NOTE:

   For mission-critical applications, Telesign recommends that you provide redundancy by implementing two URLs instead of one.

2. If you have a self-service account, enter your callback URL in the Settings section of the portal for each product. If you have a full-service account, send your callback URL to Telesign Customer Support.

3. Allow up to one business day for setup to be completed.

Retries

SMS and the SMS Verify API

For SMS and the SMS Verify API, Telesign makes up to four attempts to deliver your callback notification, with each attempt having a longer elapsed time before the next attempt:

• 1st attempt - Telesign sends the callback. If the service does not receive any HTTP response within 5 seconds, it makes the next attempt.  If a non-200 response status is received, then the service waits an additional 5 seconds and then makes the next attempt.
• 2nd attempt - Telesign sends the callback. If the service does not receive any HTTP response within 5 seconds, it makes the next attempt.  If a non-200 response status is received, then the service waits an additional 10 seconds and then makes the next attempt.
• 3rd attempt - Telesign sends the callback. If the service does not receive any HTTP response within 5 seconds, it makes the next attempt.  If a non-200 response status is received, then the service waits an additional 15 seconds and then makes the next attempt.
• 4th attempt - Final callback sent.