Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.prove.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Receive Prove Manage webhooks

Use this guide to register an HTTPS endpoint in the Prove Portal, verify each delivery with the signed JWT in X-Prove-Authorization, and process phone-change notifications from the JSON body.
Webhook events are available in the US only.

​
Prerequisites

  • Public HTTPS URL — Prove must be able to POST to your endpoint from the internet. Configure the URL in the Prove Portal.
  • Portal access — Sign-in to the Prove Portal with permission to create or open an Identity Manager project.
  • JWT verification — Your service can validate HS256 JWTs using the shared secret from the Portal (before you accept webhook JSON).
  • Delivery expectations — Prove emits events as changes are detected; delivery is best-effort and queued retries for failed delivery are not provided—design your endpoint to respond quickly and return a 2xx status when you accept a delivery.
  • No retroactive history — Events that occurred before you saved the webhook configuration are not sent later.
  • Per-identity stream — After certain outcomes (disconnect, moved out of coverage, or some phone number change situations), Prove may send no further notifications for that identity until you re-verify and re-enroll an updated number if the customer supplies one.

​
Register the endpoint in the Portal

1

Sign in to the Prove Portal

Open the Prove Portal and authenticate.
2

Create or open an Identity Manager project

Go to Projects. Create a project (Create Project) and choose Prove Identity Manager, or open an existing Identity Manager project.
3

Open webhook settings

In the project, open the Configure tab and locate Sandbox webhook settings (or the environment you are integrating).
For a throwaway test URL, use Webhook.site to mint a unique HTTPS endpoint.
4

Paste your webhook URL and save

Enter your HTTPS listener URL in the webhook field, then use Save and Test Webhook so Prove persists the configuration and issues a test POST to your endpoint.
5

Verify the JWT on every delivery

For each request, treat the body as untrusted until the JWT checks pass.
  1. Read Authorization from the X-Prove-Authorization header (Bearer <jwt>).
  2. Verify the JWT with HS256 and the shared secret from the Portal.
  3. Validate standard time claims (iat, nbf, exp), allowing about ±60 seconds clock skew. Reject tokens past exp (Prove uses about 5 minutes of validity from issuance).
  4. Confirm iss equals the literal string Prove Identity.
  5. Replay protection — Reject any jti you have already accepted within your replay window (each delivery uses a new UUID jti).
  6. Integrity — Compute SHA-256 over the raw request body bytes (before JSON parsing). Compare a constant-time hex string equality against the body_hash claim inside the JWT payload. If it fails, reject the request.
Prove also sends X-Correlation-ID on each attempt—log it for support and tracing.Example decoded payload (middle segment of the JWT):
Example JWT payload
{
  "iss": "Prove Identity",
  "iat": 1710864000,
  "nbf": 1710864000,
  "exp": 1710864300,
  "jti": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "body_hash": "8af324cfdeb52d549a2504f7ba20ea51950ee4593ce6182d2b1cea927e41944d"
}
6

Parse and handle the JSON body

After JWT and body_hash succeed, parse the JSON. Expect a top-level notifications array (Prove may send up to 100 objects per call; batches can be smaller).Handle each element using the fields below. Optional keys such as newCarrier or newLineType appear only for some event types.
FieldUse
eventIdStore for idempotency and support references.
eventHuman-readable description.
eventTypeBranch logic. Values include PHONE_NUMBER_CHANGE, DISCONNECT, PORT, LINE_TYPE_CHANGE, MOVED_OUT_OF_COVERAGE.
eventTimestampISO 8601 time from Prove.
clientCustomerIdYour customer key, if supplied on enrollment.
proveIdProve identifier for the enrolled identity.
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"
    }
  ]
}
7

Confirm the integration

  • Trigger Save and Test Webhook and confirm your handler receives a test request, returns 2xx, and passes JWT + body_hash checks.
  • Force an invalid signature or body tamper in a dev environment and confirm your service rejects the call.
  • In Sandbox, exercise at least one real notification path you plan to support and confirm your persistence and idempotency logic behave as expected.

Related topics

Account Opening VerifyAccount OpeningGet started with Prove API authenticationVerifyChallenge page requirements - Mobile Auth℠