Authenticate callbacks

Callbacks use their own version of 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 callbacks

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:

   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:

    1. For Authorization:

       1. The header value has the format TSA {Customer ID}:{signature}

          Example: TSA FFFFFFFF-EEEE-DDDD-1234-AB1234567890:n1oBUjEwVunkjfH9paeA9qHrjQw=

       2. Split the value into two parts using the space (" ") character. Save the second part.

       3. Split that string again using the ":" character. Save the second part. This is the signature.

    2. For X-TS-Authorization:

       1. Retrieve the header value you saved earlier. This is the signature.

12. 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