Validating Twilio Authy Callbacks
For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience, and new features including:
- Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, PHP, and Go.
- Access via the Twilio CLI.
- Improved visibility and insights.
- A push authentication SDK embeddable in your own application.
You are currently viewing the Authy API. New features and development will be added only to the Verify API. Check out the FAQ for more information and the migrating to Verify guide to get started.
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
- Flatten the received JSON body and sort this list in case-sensitive order and convert them to URL format
- 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
- Use HMAC-SHA256 to hash the string using your Application API Key
- Base64 Encode the digest (as described in RFC 4648 - do not include line breaks)
Here is every step summarized so you can get an idea of the whole process.
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.