Overview
The webhook allows your system to receive real-time notifications whenever a verification request is completed whether it's an onboarding or transaction screening process. Whenever a verification request you initiated is completed (Successful or otherwise), our system sends a POST request to the webhook URL you registered. This ensures your application is automatically updated without needing to pull our API.
Webhook Endpoint Requirements
Your webhook endpoint must:
- Accept POST request over HTTPS
- Parse JSON payloads
- Respond with HTTP 200 OK to acknowledge successful receipt
- Optionally verify our webhook signature
Event Type: Verification Completed
This event is triggered when a verification process is completed for both ONBOARDING and TRANSACTIN products.
Sample Webhook Payload
Successful Verification
{
"status": true,
"detail": "Verification Successful",
"product": "ONBOARDING",
"data": {
"profile_id": "ONB-34f5c102-7bde-4b87-9e23-1124f3b871dd",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+2348012345678",
"verification_status": "VERIFIED",
"created_at": "2025-10-28T12:34:56Z",
"metadata": {
"country": "NG",
"document_type": "NIN"
}
},
"reference": "ONB-34f5c102-7bde-4b87-9e23-1124f3b871dd"
}
Failed Verification
{
"status": false,
"detail": "Verification Failed: Invalid identification number",
"product": "TRANSACTION",
"data": {
"transaction_id": "TXN-91f02a4e-6e3c-11ef-8d3b-0242ac120002",
"amount": 50000,
"currency": "NGN",
"customer": {
"name": "Jane Doe",
"email": "[email protected]"
},
"verification_status": "FAILED",
"failure_reason": "Sanction match found"
},
"reference": "TXN-91f02a4e-6e3c-11ef-8d3b-0242ac120002"
}
Payload Field Description
| Field | Type | Description |
|---|---|---|
| status | boolean | Indicates whether the verification was successful (true) or not (false) |
| detail | string | A short human-readable message describing the verification outcome |
| product | string | The type of verification performed - either ONBOARDING or TRANSACTION |
| data | object | Contains the complete response object for the verification. This is identical to the |
| reference | string | A unique identifier for the verification record (profile_id for onboarding or transaction |
Response Requirements
Your webhook must return:
HTTP/1.1 200 OK
Content.Type: application/json
And optionally include:
( ''received'': true)
If your endpoint does not return 200 OK, our system will retry the webhook up to 3 times using exponential backoff.