New webhooks and reporting for Twilio Authy (2FA) and Verify (phone verification) APIs

New webhooks and reporting for Twilio Authy (2FA) and Verify (phone verification) APIs

We’ve recently updated Twilio’s market leading set of APIs for account security with reporting and event notification capabilities to give you real time, and detailed data about user verifications, authentications and other important account security events.

Protecting your customer accounts requires constant monitoring of your sign-up, authentication, and recovery processes to look for trends and areas for improvement. The ways in which users interact with your application also need constant review to deliver the most secure yet friction free experience.

Using webhooks for real-time notifications, and running reports against our API will give you valuable insight into your account security workflows. This article will go over two API updates:

• Webhooks API
• Reporting API

Knowing when something happens, as it happens

Let’s start with the webhooks API. There are a range of API interactions that will trigger a webhook event. For example when someone finishes installing the Authy app, or completes a phone number change on their account. You can use these events to update your system or modify a UX flow in real time.

The webhooks API allows you to receive real time alerts for events like these by providing a URL where the event data should be securely sent. You can find the complete list of available events in the Webhooks API documentation. Let me walk through an example of using the event device_registration_complete event to improve your 2FA onboarding experience.

When a user enables 2FA (or if you are mandating it) they need to go through some steps. These typically fall into the following:

• Starting the enablement flow
• Choosing the method of 2FA to use
• Installing the 2FA application (Not required if they choose SMS)
• Enabling 2FA by going through an initial authentication
  • Either typing in the 2FA code or responding to a push authentication

Making this flow easy and quick is essential for increasing 2FA usage, which in turn increases the security of your business and your customer’s data. Any trick you can implement to move them along quickly and without confusion is key. In the above steps, one thing that can cause friction, is the point at which you ask a user to download and install Authy, the 2FA app. This requires a user to shift context from your application to their phone to install the software they need. This is where the “device_registration_complete” event comes into play.

First add the user to the Authy API, you’ll get back an authyid which you store with your user record. Then inform the user they need to install the Authy app. When you add them to the Authy API, if they don’t have the app installed, we automatically send them an SMS message.

Then, in your code, wait for the “device_registration_complete” callback to let you know that the user has installed the Authy app. As soon as you get the callback your UX can progress to the next step, which is usually confirming the app installation is working by sending them a push authentication request to which they “Approve” to enable 2FA on their account.

The UX automatically updates when they’ve installed the Authy app, and the Authy app seamlessly presents the approval. One click and they’re done! Nice and simple.

Webhooks can also be used to get other updates. Both in the Authy app and also via the authy.com website, a user has the ability to change their phone number. When you use the Authy API to send 2FA codes via SMS, we will always use the latest number the user has given us, however it may be useful for you to know when this changes so you can update your customer record.

Bulk reports on what’s been going on

The reporting API offers the same data as the webhooks API, except instead of getting single notifications (callbacks) in real time, you can query the API for a batch of events, filtering by time period and type of events.

Taking the same event above, you might want to graph instances of people installing the Authy app when enabling 2FA for your application. The following:

Will return JSON with all the Authy app install events, for users in your application, in Jan 2018. You can then bulk import this data into your own reporting systems to build dashboards that give you an indication of the health of your users. The example below shows users who have lost devices or changed their phone number and are interacting with authy.com or the Authy apps to self service recovering access to your application. Useful data to know how many support tickets you are avoiding due to the self service capabilities of our 2FA API.

These API updates are therefore great sources of data to inform the building of rich user authentication and phone verification experiences.

It’s this sort of data that makes using the Twilio Authy and Verify APIs so valuable. Quick to implement and abstracting all the complex telecoms and security logic, the APIs are a much better choice than trying to build your own 2FA or phone verification implementation from scratch. Combined with the fact that the 2FA API offers a free mobile client for TOTP and push authentication and that authy.com exposes self service recovery processes, your ongoing cost of supporting users is dramatically reduced. To get started, sign up at Twilio.com and learn more in our documentation. There are also some awesome samples in github so you can be playing with these APIs super quick. Reporting Samples and Webhook samples.