Prove Webhook Events
Last updated August 11th, 2026
Overview
Mono Prove uses webhooks to deliver key information about identity verification sessions. When a verification event occurs (initiation, success, cancellation, failure, or expiration), Mono sends a POST request to your designated URL. This allows you to receive and process verification updates, such as session status and customer data, within your system's workflow.
Prerequisites
Before you begin receiving webhooks, you must:
- Configure a POST webhook endpoint on your server.
- Add the webhook URL in the Mono dashboard for your app.
- Return a
2xxresponse after successfully processing each event.
Security
Validate every webhook request with your webhook secret before processing the payload. See the Webhook Setup Guide for the recommended verification flow.
Webhook Event Types
| Event | Description |
mono.prove.data_verification_initiated | Verification session was successfully created |
mono.prove.data_verification_successful | Customer data verified and successfully shared with the business |
mono.prove.data_verification_cancelled | Customer cancelled their data verification |
mono.prove.data_verification_expired | Verification expired after 24 hours of non-completion |
mono.prove.data_verification_awaiting_review | Verification transitioned to manual review |
mono.prove.data_verification_rejected | Face ID verification was rejected |
mono.prove.data_verification_failed | Verification reached the failed terminal status |
Verification Events
Verification Initiated (mono.prove.data_verification_initiated)
This webhook is triggered when the initiate session is successfully created.
Request
{
"event": "mono.prove.data_verification_initiated",
"data": {
"app": "67b5c78477237d041a069bd0",
"business": "60cc8f95ba1772018c5c6b1d",
"id": "PRVQ1B9JR5123",
"status": "pending",
"reference": "test-reference-03",
"created_at": "2025-02-28T09:24:32.823Z",
"kyc_level": "tier_1",
"bank_accounts": false,
"is_blacklisted": false,
"blacklist_count": 0,
"meta": {
"ref": "1234"
}
}
}
Verification Successful (mono.prove.data_verification_successful)
This webhook is triggered when the customer data is verified and successfully shared with the business.
Request
{
"event": "mono.prove.data_verification_successful",
"data": {
"id": "PRVJM0POABY04",
"customer": {
"id": "67c07e5dcde95dbf8c2f2c7e",
"name": "Tunde Adebayo",
"email": "test4@example.com"
},
"reference": "ref-9",
"status": "successful",
"created_at": "2025-03-04T12:53:49.839Z",
"kyc_level": "tier_1",
"bank_accounts": true,
"data_access": {
"start_date": null,
"end_date": null,
"type": "permanent"
},
"app": "67b5c78477237d041a069bd0",
"business": "60cc8f95ba1772018c5c6b1d"
}
Verification Cancelled (mono.prove.data_verification_cancelled)
This webhook is triggered when a customer cancels their data verification.
Request
{
"event": "mono.prove.data_verification_cancelled",
"data": {
"id": "PRVG62L211UN2",
"customer": {
"id": "67c07e5dcde95dbf8c2f2c7e",
"name": "Tunde Adebayo",
"email": "test4@example.com"
},
"reason": "I am not comfortable sending my ID photo",
"reference": "ref-7",
"status": "cancelled",
"created_at": "2025-03-03T15:01:15.587Z",
"kyc_level": "tier_2",
"bank_accounts": true,
"app": "67b5c78477237d041a069bd0",
"business": "60cc8f95ba1772018c5c6b1d"
}
Verification Expired (mono.prove.data_verification_expired)
This webhook is triggered when a customer's data verification expires after 24 hours of non-completion.
Request
{
"event": "mono.prove.data_verification_expired",
"data": {
"id": "PRVXH82GO8123",
"reference": "ref-6",
"status": "expired",
"created_at": "2025-03-03T12:20:20.829Z",
"kyc_level": "tier_1",
"bank_accounts": true,
"app": "67b5c78477237d041a069bd0",
"business": "60cc8f95ba1772018c5c6b1d",
"attempts": 0, // otp authentication attempts
"error_logs": [ //last 3 errors before link expiration
{
"timestamp": 1741006286345,
"message": "Unable to complete request"
},
{
"timestamp": 1741006398337,
"message": "Unable to complete request"
},
{
"timestamp": 1741009395153,
"message": "Unable to complete request"
}
]
}
Verification Awaiting Review (mono.prove.data_verification_awaiting_review)
This webhook event is sent after a customer makes three consecutive failed attempts for facial verification, the widget will automatically transition to the manual review state and this webhook event is sent.
Request
{
"event": "mono.prove.data_verification_awaiting_review",
"data": {
"id": "PRVJM0POABY04",
"customer": {
"id": "67c07e5dcde95dbf8c2f2c7e",
"name": "Tunde Adebayo",
"email": "test4@example.com",
"phone":"08123456789"
},
"reference": "ref-9",
"status": "awaiting_review",
"created_at": "2025-03-04T12:53:49.839Z",
"kyc_level": "tier_1",
"bank_accounts": true,
"data_access": {
"start_date":null,
"end_date":null,
"type": "permanent"
},
"app": "67b5c78477237d041a069bd0",
"business": "60cc8f95ba1772018c5c6b1d"
}
Verification Rejected (mono.prove.data_verification_rejected)
This webhook event is sent when the Face Id verification is rejected.
Request
{
"event": "mono.prove.data_verification_rejected",
"data": {
"id": "PRVXKVZVJKIF7",
"customer": {
"id": "6895e4317b220b847b9774b3",
"name": "Chinedu Eze",
"email": "test3@example.com",
"phone": "+2348123456789"
},
"reason": "Face doesn’t match ID",
"reference": "bm04b67lntpdrer90y4w3m8n",
"status": "rejected",
"created_at": "2025-11-12T11:48:08.697Z",
"kyc_level": "tier_1",
"bank_accounts": false,
"app": "67ac702ab84447f98209ecec",
"business": "60cc8f95ba1772018c5c6b1d",
"live_mode": true
}
}
Verification Failed (mono.prove.data_verification_failed)
This webhook fires when a Prove verification reaches the failed terminal status. Once sent, the data request is marked failed and no further review is possible.
It can be triggered in the following scenarios:
1. Rate limit: When a customer attempts to verify the same identity type (e.g. NIN) and fails four times, the fourth attempt marks the request as failed, you are billed for that attempt and this webhook is sent.
Request
{
"data": {
"event": "mono.prove.data_verification_failed",
"data": {
"id": "PRVHX2KLMN0Q4",
"customer": {
"id": "65b3e8d1f4c2a9b7e6d5f80a",
"name": "Amina Bello",
"email": "test@example.com",
"phone": "+2348031122334"
},
"reference": "bello-482",
"status": "failed",
"created_at": "2026-08-10T08:32:16.731Z",
"kyc_level": "tier_2",
"bank_accounts": false,
"meta": {
"attemptedIdentities": {
"nin": 3,
"bvn": 3
}
},
"identities": [],
"app": "67e1b3f2a9c84d5e6f0a1b2c",
"business": "61a2b3c4d5e6f708192a3b4c",
"live_mode": true,
"reason": "Identity verification failed. You’ve exceeded the limit for attempts, and your verification will now be marked as failed."
}
}
}
2. Identities not fully verified: After the image review is approved, each shared identity's verification checks (image quality, expiry date, date of birth, name, authenticity, address) are evaluated. If any identity has a verification flag that is explicitly false, meaning that identity did not pass verification, the request is marked failed and this webhook is sent.
Request
{
"data": {
"event": "mono.prove.data_verification_failed",
"data": {
"id": "PRVW7MDTQN2C9",
"customer": {
"id": "68b2c7d54f3e9a1c8d6f4b2a",
"name": "Ngozi Adaeze Okafor",
"email": "test2@example.com",
"phone": "+2348098765432"
},
"reason": "NIN dateOfBirth verification failed",
"reference": "okafor-739",
"status": "failed",
"created_at": "2026-08-10T16:57:59.112Z",
"kyc_level": "custom",
"bank_accounts": false,
"identities": [
"nin",
"passport_id"
],
"app": "67f2c9a41d0b9e7c3a5b6c8d",
"business": "61a2b3c4d5e6f708192a3b4c",
"live_mode": true
}
}
}
Note
This webhook does not fire when the identity lookup is down or there is downtime. In such cases the verification does not reach the failed terminal state, so nothing is counted, charged or sent via webhook. The widget simply receives a generic "unable to complete request" error.