Skip to main content
The following endpoints apply to this flow:

​
Prerequisites

  • Server-side SDK installed for your platform.
  • Authentication credentials from the Prove Portal configured in your environment.
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",
})
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

Perform Batch Enrollment (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",
  },
  {
    PhoneNumber: "2001004035", 
  },
}

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 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

Open Webhook Configuration

Using the Configure tab, select the Configure button next to the Sandbox webhook.
If you would like a sample URL to test, you can use Webhook.site to generate a unique URL for testing.
Screenshot of the webhook configuration screen in the Prove Portal, showing where to enter the webhook URL.
4

Enter Webhook Endpoint URL

Enter your webhook endpoint URL in the provided field.
5

Save and Test Webhook

Select Save and Test Webhook. This saves your configuration and sends a test webhook to your endpoint.
6

Authenticate Webhook

The webhook URL requires authentication using Prove’s secret for JSON Web Token (JWT). The JWT is a synchronous token using the HS256 algorithm.Use this secret to sign the JWT token that Prove sends with the webhook notifications. Add the appropriate code snippet from the webhook configuration to your server-side implementation, replacing whsec_your_secret with the secret provided by the Portal.
Prove generates the secret when you enter the appropriate URL and you select Save and Test Webhook or Configure Webhook.
7

Parse the Webhook Payload

The following snippet shows an example of each type of change event you could receive from Prove. Each notification comes 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"
    }
    ]
}
​
eventId
string
A unique event ID to reference if you need support.
​
event
string
A description of the event.
​
eventType
string
The event type. Identity Manager supports: PHONE_NUMBER_CHANGE, DISCONNECT, PORT, LINE_TYPE_CHANGE, and MOVED_OUT_OF_COVERAGE.
​
eventTimestamp
string
The time the event is sent.
​
clientCustomerId
string
The client customer ID associated with the identity.
​
identityId
string
A unique Prove-generated identifier.
8

Access Production

Once you have successfully tested the webhook and finished your implementation, test your production webhook URL.
Why Am I Not Receiving Notifications?
  • Prove doesn’t send retroactive notifications that occur before configuring the webhook.
  • Deactivated identities don’t generate webhook notifications until reactivated.
  • A phone number change, disconnect, or moved out of coverage event results in no further notifications for that identity. If your customer provides an updated phone number, we’d recommend completing verification for this number and then enrolling the updated phone number.