This guide provides instructions to integrate Prove Verified Users. Implementation guides for server-side and client-side SDKs are available. Prove provides server-side SDKs in the following languages: Go, Java, TypeScript, and JavaScript. If you implement using a different back end language, you can interact with the API endpoints.

To integrate Verified Users with possession, use one of the client-side SDKs.

For mobile network operator (MNO) consent information in the following countries, contact your Prove representative:

  • Canada
  • The United Kingdom
  • Germany
  • France

​
Prerequisites

Before you begin implementing, ensure you have Prove Sandbox credentials from the Developer Portal. To access Sandbox credentials, follow the steps outlined on the Authentication page.

​
Implement Verified Users

The Verified Users solution is implemented in three parts: client-side, server-side, and webhook. The client-side handles the user interface, the server-side handles the API calls, and the webhook handles phone change notficiations.

​
Webhook Notifications

Webhook notifications are only available for US-based phone numbers.

Configure webhooks to receive change events notifications for previously verified, enrolled customers.

Here’s how to get these webhook notifications up and running:

1

Access the Portal

Login to the Portal.

2

Find Your Project

Navigate to your Verified Users project.

3

Configure Webhook

Using the Configure tab, select the Configure button next to the Sandbox webhook. You will be presented with a screen that looks like this:

Enter the URL of your webhook endpoint and select Save and Test Webhook. This will save your configuration and send a test webhook to the URL you provided.

If you would like a sample URL to test, you can use Webhook.site to generate a unique URL for testing.

4

Authenticate Webhook

The webhook URL must be authenticated using Prove’s JWT secret. The JWT is a synchronous JWT using HS256 (synchronous algorithm).

This secret is used to sign the JWT token that Prove sends with the webhook notifications. Open the webhook configuration and add the appropriate code snippet to your server-side implementation, replacing whsec_your_secret with the secret provided by the Portal.

The secret value is autogenerated when the appropriate URL is entered and you select Save and Test Webhook or Configure Webhook.

5

Parse the Webhook Payload

The following snippet shows an example of each type of change event you could receive from Prove. Each notification will come as an array of event objects.

Example Payload
{
    "notifications": [
        {
            "eventId": "6ab42d26-8ed2-453f-a4a4-ac305aa50332",
            "event": "phone number change detected",
            "eventType": "PHONE_NUMBER_CHANGE",
            "eventTimestamp": "2025-01-23T10:11:12Z",
            "clientCustomerId": "74ed2189-bde0-4f09-9a7b-0f534259b7b5",
            "identityId": "64ec34e4-6b91-427c-839c-b443dd1570fc"
        },
        {
            "eventId": "0c07d8e3-185c-4b5b-a27b-71ad9ee916b1",
            "event": "phone number disconnected",
            "eventType": "DISCONNECT",
            "eventTimestamp": "2025-01-23T10:11:12Z",
            "clientCustomerId": "f1ea13d2-22ed-433f-94b8-a9026d265797",
            "identityId": "b479a9cb-4dbd-424f-b51e-e4e5bdef8541"
        },
        {
            "eventId": "cbb5f37f-d8e2-4044-955e-a5beec4ddf63",
            "event": "phone number moved out of coverage",
            "eventType": "MOVED_OUT_OF_COVERAGE",
            "eventTimestamp": "2025-01-23T10:11:12Z",
            "clientCustomerId": "62467a14-7ac1-4e36-83f9-77f44ec26f16",
            "identityId": "c3a1a59f-d255-4293-b167-9d007b40db6f"
        }
    ]
}
6

Access Production

Once you have successfully tested the webhook and finished your implementation, reach out to your Prove representative to enable your production webhook URL. This will allow you to receive notifications for live events.

Why Am I Not Receiving Notifications?

  • Prove will not send retroactive notifications that occur before the webhook is configured.

  • By nature of each change event, an event triggering for an identityId will result in no further notifications for that identity.

    In the event your customer provides an updated phone number, we’d recommend initiating a new verification with the updated identity information. If verification is successful, Prove will monitor the updated phone number.