Skip to main content
Prove Manage helps businesses proactively manage consumers’ phone numbers and other vital identity attributes as they change throughout their lifecycle, providing continuous monitoring and alerts about identity changes. Prove notifies of It provides phone risk change events based on the connection between an enrolled Prove ID and their phone number via webhook. Updates can include the following attributes:
  • Disconnects
  • Number Changes
  • Line Type Changes
  • Ports
  • Moved Out of Coverage
Webhook events are available in the US.

​
Prerequisites

  • Webhook URL: A URL that Prove calls to send notifications of phone change events for a particular Prove ID. This URL must be publicly accessible and configured in the Prove Portal.
Prove sends change notifications via webhook as the platform identifies and processes a consumer change. Webhook queuing for failed events isn’t available but delivery is on a best effort basis.

​
Webhook setup and authentication

Prove Manage sends phone risk change events via webhooks to your specified endpoint. Integration requires configuring your endpoint in the Prove Portal and implementing JWT verification to secure the data exchange.
1

Access the Portal

Login to the Prove Portal.
2

Create and Navigate To Your Project

Navigate to the Projects tab. Select Create Project and pick Prove Identity Manager.
3

Open Webhook Configuration

After navigating to your Identity Manager project, use the Configure tab to configure the Sandbox webhook.
If you would like a sample URL to test, you can use Webhook.site to generate a unique URL for testing.
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

Prove signs every delivery attempt using a short-lived JSON Web Token (JWT). You must verify the signature using the secret provided in the Portal and validate the claims in the X-Prove-Authorization header. The JWT is a synchronous token using the HS256 algorithm.JWT Authentication Reference
  • Header: X-Prove-Authorization: Bearer <JWT>
  • Algorithm: HS256 (HMAC-SHA256)
  • Secret: The shared secret from the Prove Portal.
  • Correlation: X-Correlation-ID is provided for tracking delivery attempts.
Payload Claims Reference
ClaimTypeDescription
issstringIssuer. Prove sets this to the literal string Prove Identity. Use it to confirm the token was minted in this integration context.
iatintegerIssued at — Unix time when the token was created.
nbfintegerNot before — Unix time before which the token must not be accepted. Prove sets nbf equal to iat.
expintegerExpiration — Unix time after which the token must be rejected. Tokens are valid for 5 minutes from issuance.
jtistringJWT ID — A new UUID string for each delivery attempt. Use it for replay detection: reject duplicate jti values you have already accepted within your replay window.
body_hashstringHex-encoded SHA-256 of the raw webhook JSON body, the POST body as bytes, before parsing. Compute SHA256 and compare as constant-time hex string equality to this claim. If they differ, the body was altered in transit or the token does not match this request. The body_hash is a private claim name, per RFC 7519 §4.2, chosen to mirror the OIDC *_hash pattern used for at_hash and c_hash in OpenID Connect Core 1.0 §3.1.3.
Sample claims setThe payload is JSON inside the JWT, seen after base64url-decoding the middle segment.
Example
{
"iss": "Prove Identity",
"iat": 1710864000,
"nbf": 1710864000,
"exp": 1710864300,
"jti": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"body_hash": "8af324cfdeb52d549a2504f7ba20ea51950ee4593ce6182d2b1cea927e41944d"
}
Security Best Practices
  • Verifying body_hash: To ensure the payload wasn’t tampered with, compute SHA256 and compare the result to the body_hash claim using a constant-time comparison. Perform this check before parsing the JSON into an object.
  • Replay Detection: Store jti values within the 5-minute validity window. If you receive a webhook with a jti you have already processed, reject it.
  • Clock Skew: Allow for a small margin, ±60s, when validating iat and exp to account for minor server time differences.
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. Prove returns batches of up to 100 events per webhook call, but the batch size can be smaller based on the number of events that occur.
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",
        "proveId": "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",
        "proveId": "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",
        "proveId": "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",
        "proveId": "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",
        "proveId": "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.
​
proveId
string
A unique Prove-generated identifier.
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 to enroll the updated phone number.