Verify API Webhooks

Webhooks are an extension of an API - instead of your code requesting data from our API platform, Vonage sends the data to you via a web request to your application. The Verify API webhook receives status updates on your requests, and will be the result of an earlier API call - this type of webhook is also called a "callback".

Receiving webhooks

To allow the Vonage servers to send data to your application via webhooks, you need to set up a webserver to receive the incoming HTTP requests. You also need to specify the URL of each webhook on your webserver so that data can be sent to each one.

To start using Verify webhooks:

  1. Create a Vonage account.
  2. Write scripts to handle the information sent or requested by Vonage. Your server must respond with a 200 or 204 HTTP response, as anything other than a 2xx code will cause the Vonage servers to re-attempt callback delivery.
  3. Publish your scripts by deploying to a server. For local development, try Ngrok.
  4. Configure your Verify webhook endpoint.
  5. Take an action (such as sending an SMS verification request) that will trigger that webhook.

Information about your request is then sent to your webhook endpoint.

Configure your Verify webhook URLs

The Verify API supports a Status webhook, which is configured in your application settings in the developer dashboard:

Webhooks can be configured on the customer dashboard

This is used to send status updates (for example, progress or completion events) for your Verify requests.

Testing webhooks locally

In order to test the correct functioning of webhooks on your locally running application, you will need to create a secure tunnel between Vonage and your application. You can do this with a secure tunnel application such as Ngrok. See Testing with Ngrok for more information.

Signed Webhooks

Verify webhooks are signed by default. Signed webhooks allow your application to verify a request is coming from Vonage and its payload has not been tampered with during transit. When receiving a request, the incoming webhook will include a JWT token in the authorization header which is signed with your signature secret.

More information on decoding signed webhooks can be found here.

Types of Callback

Events Callback

An inbound events webhook. This will show the final result of your request using the status field:

  • completed - the request was completed and the user was successfully verified.
  • blocked - the request was blocked due to velocity rules, or the number provided is a VOIP.
  • failed - the request failed as the number given was not a valid number.
  • expired - the request was not completed within the given time limit.
  • user_rejected - the user entered an incorrect pin.
  • cancelled - the user canceled the request before completing the authentication process.
  • action_pending - the user has not taken any action to start the authentication procedure. For example, the check_url that the user is given to begin silent authentication has happened yet.

Silent Authentication

As part of a Silent Authentication request, you will receive an event callback to your webhook - for example:

Summary Callback

Summary callbacks contain an inbound status update for a particular request. As you can see in the below example, there are two Status fields - the first is the status of the overall request, and the others show the result of each channel used in the workflow.

For the request, there are six different Status values you may see:

  • completed - the request was completed and the user was successfully verified.
  • failed - the request failed as the number given was not a valid number or not a mobile IP.
  • expired - the request was not completed within the given time.
  • user_rejected - the user entered an incorrect pin three times, which terminated the workflow.
  • blocked - the request was blocked due to velocity rules, or the number provided is a VOIP.
  • cancelled - the user canceled the request before completing the authentication process.

In the workflow, there are seven different Status values you may see when using the API:

  • unused - the channel was not used as the request was converted by a previous channel in the workflow.
  • completed - the channel was used, and resulted in a successful verification.
  • failed - any channel defined in the workflow failed because the number given was not a valid number or not a mobile IP, or the country the user was located in is not covered by Verify.
  • expired - any channel defined in the workflow expired as the OTP was not entered within the given time limit.
  • blocked - SMS/Voice channel has been blocked due to velocity rules.
  • user_rejected - the user entered an incorrect pin three times, which terminated the workflow for the channel used.
  • cancelled- a specific channel's authentication process defined in the workflow was cancelled while it was still in progress.

This example shows an update for a completed verification request. The first channel attempted to use SMS, but the request expired. Next, WhatsApp was used and the user was verified successfully. As the Voice channel was not attempted, the status shows as unused.

To complete the silent authentication request, you will need to read the check_url and pass it to the client to authenticate.