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, Voice, Voice Verify, and Inbound SMS products.

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

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

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 Authentication for more details.
• Accepts: application/json
• Responds With: application/json

📘

NOTE:

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

Request body

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

This example is for an SMS Verify transaction. Product-specific parameters that are not part of the general schema are highlighted in the code.

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" 
}

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.
4. You will receive callback notifications after both of the following occur:
   • A transaction completes.
   • Telesign determines the final status of the transaction (refer to the section Transaction Status Codes on the Codes, Languages, and Timezones page for a list of status codes that may be returned).
5. If Telesign is unable to deliver your callback notification on the first attempt, the Telesign server tries again. If the second attempt fails, the server makes a third and final attempt.

Here is a diagram of what the notification flow looks like, using SMS Verify for the example. The flow is similar for other products.

Authentication

Telesign sends callbacks with headers that can be used for Digest authentication. Just as you must digitally sign all your requests to Telesign when using Digest authentication, Telesign signs all of its requests to your Transaction Callback Service. The details of the signature are slightly different however from those used when sending a request to Telesign.

How to authenticate

To authenticate the callback, follow these steps:

1. Make your Customer ID and API Key accessible to your integration code. For help finding these items, see the support article How do I find my Customer ID and API Key?.

• Example Customer ID: FFFFFFFF-EEEE-DDDD-1234-AB1234567890
• Example API Key: ABC12345yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==

2. Save the value of one of two headers from the request from Telesign (both are always included):

• Authorization
• x-ts-authorization

3. Convert the body of the request to a string (decode using UTF-8 for a JSON payload) and save it to use in a later step. This is your string-to-sign.

📘

NOTE:

Unlike when you make a request to Telesign, this signature only includes the body of the message.

4. Encode your string-to-sign using UTF-8 encoding.
5. Base-64 decode your API Key.
6. Save the hashing method ("auth_method") you are using to authenticate. Currently only "HMAC-SHA256" is supported. It can be either upper-cased or lower-cased.
7. Create a new HMAC object using your decoded API Key, your string-to-sign, and the same "auth_method" string you saved earlier. Here's an example of how you might do that in Python:

hmac_obj = hmac.new(decoded_api_key, encoded_string_to_sign, digestmod=auth_method)

8. Create a digest from this HMAC object.
9. Decode this digest with UTF-8 encoding.
10. Based-64 encode the decoded digest. This is your expected signature.
11. Parse the signature from the Authorization or x-ts-authorization header value you saved earlier. The header value has the format "TSA" + a space + Customer ID + ":" + signature. Split the value into two parts using the space (" ") character. Save the second part.
12. Split that string again using the ":" character. Save the second part. This is the signature.
13. Compare the signature to the expected signature. Here is an example of how to do that using Python:

hmac.compare_digest(signature, expected_signature)

Sample code

Feel free to copy this code for authenticating requests from Telesign and adapt it to your integration:

• Python
• Java