Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Validating Twilio Authy Callbacks

When using Webhooks with push authentications, Twilio will send a callback to your application's exposed URL when a user interacts with your ApprovalRequest. While testing, you can accept all incoming webhooks, but in production, you'll need to verify the authenticity of incoming requests.

Twilio sends an HTTP Header X-Authy-Signature with every outgoing request to your application. X-Authy-Signature is a HMAC signature of the full message body sent from Twilio hashed with your Application API Key (from Authy in the Twilio Console).

You can find complete code snippets here on Github.

Verify a Twilio Authy Callback

Checking the authenticity of the X-Authy-Signature HTTP Header is a 6 step process.

  • Create a string using the Webhook URL without any parameters
Loading Code Sample...
      
      
      
      
      Use the webhook URL without any parameters to create a string.

      Create a Webhook URL String

      Use the webhook URL without any parameters to create a string.
      • Flatten the received JSON body and sort this list in case-sensitive order and convert them to URL format
      Loading Code Sample...
          
          
          
          
          Sort all received parameters in alphabetical, case-sensitive order after converting them to URL format.

          Sort the Parameters

          Sort all received parameters in alphabetical, case-sensitive order after converting them to URL format.
          • Grab the nonce from the X-Authy-Signature HTTP Header
          Loading Code Sample...
              
              
              
              
              Grab the nonce from the X-Authy-Signature HTTP Header.

              Get the Nonce

              Grab the nonce from the X-Authy-Signature HTTP Header.
              • Join the nonce, HTTP method ('POST'), and the sorted parameters together with the vertical pipe, ('|') character
              Loading Code Sample...
                  
                  
                  
                  
                  Using the vertical pipe ('\') character, join the nonce, HTTP Method, and sorted parameters.

                  Join the Nonce, Method, and Params

                  Using the vertical pipe ('\') character, join the nonce, HTTP Method, and sorted parameters.
                  • Use HMAC-SHA256 to hash the string using your Application API Key
                  Loading Code Sample...
                      
                      
                      
                      
                      Use HMAC-SHA256 to hash the resulting string with your Application API Key from the console.

                      Hash the Combined String with HMAC-SHA256

                      Use HMAC-SHA256 to hash the resulting string with your Application API Key from the console.
                      • Base64 Encode the digest (as described in RFC 4648 - do not include line breaks)
                      Loading Code Sample...
                          
                          
                          
                          
                          Follow RFC4648 to Base64 encode the digest

                          Encode the Digest with Base64

                          Follow RFC4648 to Base64 encode the digest

                          Here is every step summarized so you can get an idea of the whole process.

                          Loading Code Sample...
                              
                              
                              
                              
                              Overview of the steps needed to verify an incoming Twilio webhook for Push Notifications.

                              Verify an Incoming Two-factor Authentication Webhook

                              Overview of the steps needed to verify an incoming Twilio webhook for Push Notifications.

                              Once you have encoded the digest, you can compare the resulting string with the X-Authy-Signature HTTP Header. If they match, the incoming request is from Twilio. If there is a mismatch, you should reject the request as fraudulent.

                              Need some help?

                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                              Loading Code Sample...