​
Prerequisites

  • Sandbox credentials: Ensure you have Prove Sandbox credentials from the Developer Portal. To access Sandbox credentials, follow the steps outlined on the Authentication page. To access the Prove API, you’ll need to use your OAuth client ID and client secret. You can load these from environment variables or another method:
// Get environment variables.
clientID := os.Getenv("PROVE_CLIENT_ID")
if len(clientID) == 0 {
  return fmt.Errorf("missing env variable: %s", "PROVE_CLIENT_ID")
}

clientSecret := os.Getenv("PROVE_CLIENT_SECRET")
if len(clientSecret) == 0 {
  return fmt.Errorf("missing env variable: %s", "PROVE_CLIENT_SECRET")
}

proveEnv := "uat-us" // Use UAT in US region.

// Create client for Prove API.
client := provesdkservergo.New(
  provesdkservergo.WithServer(proveEnv),
  provesdkservergo.WithSecurity(components.Security{
    ClientID:     provesdkservergo.String(clientID),
    ClientSecret: provesdkservergo.String(clientSecret),
  }),
)
Token Expiration

The OAuth token expires after 60 minutes, requiring you to get another token.

  • Server-side SDK: Install the server-side SDK of your choice by running a command in your terminal, or by using a dependency management tool specific to your project.
# The Go library is hosted on GitHub so you can use this command to import it
# to your Go application.
go get github.com/prove-identity/prove-sdk-server-go

# Ensure you import the SDK in your code like this:
import (
	provesdkservergo "github.com/prove-identity/prove-sdk-server-go"
	"github.com/prove-identity/prove-sdk-server-go/models/components"
)

​
Implement Prove Identity Manager

1

Enroll Identity for Monitoring

Use the Enroll Identity endpoint to enroll a single customer for monitoring:

// Enroll a single identity for monitoring
rspEnrollIdentity, err := client.IdentityManager.V3EnrollIdentity(ctx &components.V3EnrollIdentityRequest{
  PhoneNumber: "2001004031",
  ClientCustomerId: provesdkservergo.String("customer-123"),
})
if err != nil {
  return fmt.Errorf("error creating identity: %w", err)
}

The function returns:

  • identityId: a unique Prove-generated identifier for the enrolled identity.
  • success: if true, the request was successful and the identity was created.
2

Batch Enroll Identities (Optional)

For bulk operations, use the Batch Enroll Identities endpoint to enroll up to 100 customers at once:

// Enroll multiple identities in a batch
identities := []components.IdentityItem{
  {
    PhoneNumber: "2001004031",
    ClientCustomerId: provesdkservergo.String("customer-123"),
  },
  {
    PhoneNumber: "2001004032", 
    ClientCustomerId: provesdkservergo.String("customer-124"),
  },
}

rspBatchEnroll, err := client.IdentityManager.V3BatchEnrollIdentities(ctx, &components.V3BatchEnrollIdentitiesRequest{
  Identities: identities,
})
if err != nil {
  return fmt.Errorf("error batch enrolling identities: %w", err)
}

​
Webhook Notifications

Webhooks are the method by which Prove sends risk change events. Webhook integration is necessary in order to receive change notifications for enrolled consumers.

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 Identity Manager 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": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "event": "phone number change detected",
        "eventType": "PHONE_NUMBER_CHANGE",
        "eventTimestamp": "2025-01-23T10:11:12Z",
        "clientCustomerId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "identityId": "81d3829a-7207-4fd7-9a78-2dbf33fd54ad"
    },
    {
        "eventId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "event": "phone number disconnected",
        "eventType": "DISCONNECT",
        "eventTimestamp": "2025-01-23T10:11:12Z",
        "clientCustomerId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "identityId": "81d3829a-7207-4fd7-9a78-2dbf33fd54ad"
    },
    {
        "eventId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "event": "phone number ported to new provider",
        "eventType": "PORT",
        "eventTimestamp": "2025-01-23T10:11:12Z",
        "clientCustomerId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "identityId": "81d3829a-7207-4fd7-9a78-2dbf33fd54ad",
        "newCarrier": "AT&T Wireless"
    },
    {
        "eventId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "event": "phone number line type changed",
        "eventType": "LINETYPE_CHANGE",
        "eventTimestamp": "2025-01-23T10:11:12Z",
        "clientCustomerId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "identityId": "81d3829a-7207-4fd7-9a78-2dbf33fd54ad",
        "newLineType": "Mobile"
    },
    {
        "eventId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "event": "phone number moved out of coverage",
        "eventType": "MOVED_OUT_OF_COVERAGE",
        "eventTimestamp": "2025-01-23T10:11:12Z",
        "clientCustomerId": "c3702333-ddd0-4aad-8f8f-c2813c1dd253",
        "identityId": "81d3829a-7207-4fd7-9a78-2dbf33fd54ad"
    }
    ]
}
6

Access Production

Once you have successfully tested the webhook and finished your implementation, configure and test 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.

  • Deactivated identities will not generate webhook notifications until reactivated.

  • A phone number change, disconnect, or moved out of coverage event will result in no further notifications for that identity.

    In the event your customer provides an updated phone number, we’d recommend completing verification for this number and then enrolling the updated phone number.

​
Test Your Prove Implementation

Next, reference the Sandbox test scenarios to test users and simulate different behaviors encountered in production.

Production Launch

To launch in Production, please contact your Prove representative.