POST request to your pre-configured callback URL when a verification event occurs. See Webhooks for setup details and best practices.
Headers
string
required
application/jsonstring
required
SHA256 HMAC signature of the raw request body, signed with your secret key. See Signature verification.
Body
string
required
Unique identifier for this notification. Use for deduplication.
string
required
Event type. One of
VERIFICATION.STATUS_CHANGE or VERIFICATION.IDENTITY_DOCUMENT_CHANGE.string
required
Always
VERIFICATION.string
required
ISO 8601 timestamp of when the event was created.
object
required
The full verification object.
Show data properties
Show data properties
string
Verification ID.
string
Your external identifier for this verification.
array
Array of verification requirements (
FACE_SCAN, DOCUMENT_SCAN).string
URL where the user completes the verification.
string
Current status:
CREATED, STARTED, EXPIRED, USER_DATA_COLLECTED, REVIEW, APPROVED, or DECLINED.string
ISO 3166-1 alpha-2 country code associated with this verification (e.g.,
ZM, KE, NG).string
Phone number associated with this verification (e.g.,
+260971234567). Null if not provided.string | null
shortId of the workflow running this verification. Null until the workflow is pinned: a verification created with neither
workflowId nor requirements runs on the country default and is pinned when it starts, so this is null on the CREATED event and set from STARTED onward. Also null for verifications created before pawaPass stored the workflow, or before workflows existed.object
Review outcome details. Null when verification has not been reviewed or no review reason is available.
Show reviewResult properties
Show reviewResult properties
string
required
Decline reason category code (e.g.,
CAPTURE_ISSUE, DOCUMENT_VALIDITY, DOCUMENT_VALIDITY_CONCERN, IDENTITY_VERIFICATION, SYSTEM_PROCESS, OTHER). Null for legacy reasons without a category.string
required
Specific decline reason code (e.g.,
ONE_SIDE_MISSING, DOCUMENT_EXPIRED, DOCUMENT_FAKE).boolean
required
Whether the decline reason is flagged sensitive. When
true, avoid exposing the specific reason to the end user.object
Optional metadata provided when creating the verification.
string
Redirect URL after successful verification.
string
Redirect URL on error.
string
Support URL shown during verification.
object
Extracted identity document data. Null if not yet available.
Show identityDocument properties
Show identityDocument properties
string
Document type. One of
PASSPORT, NATIONAL_ID, DRIVER_LICENSE, REFUGEE_ID, VOTER_ID, RESIDENCE_PERMIT.string
ISO 3166-1 alpha-2 country code of the issuing country (e.g.,
ZM, KE, NG).string
Serial number of the document.
string
National identification number.
string
First name as extracted from the document.
string
Last name as extracted from the document.
string
Date of birth in
YYYY-MM-DD format.string
Place of birth.
string
Nationality.
string
Document expiration date in
YYYY-MM-DD format.string
Document issue date in
YYYY-MM-DD format.string
Authority that issued the document.
string
Location where the document was issued.
string
ISO 8601 timestamp.
string
ISO 8601 timestamp.
object
string
Email/identifier of the person who created this verification.
string
ISO 8601 expiration date of the verification session.
string
ISO 8601 creation timestamp.
string
ISO 8601 last update timestamp.
{
"notificationId": "a1b2c3d4-5678-9012-abcd-ef1234567890",
"type": "VERIFICATION.STATUS_CHANGE",
"object": "VERIFICATION",
"createdAt": "2025-08-20T10:15:00.000Z",
"data": {
"id": "aB1cD2eF",
"externalId": "user-zm-98765",
"requirements": [
{ "type": "FACE_SCAN" },
{ "type": "DOCUMENT_SCAN" }
],
"url": "https://app.pawapass.com/your-company/aB1cD2eF",
"status": "APPROVED",
"country": "ZM",
"phoneNo": "+260971234567",
"workflowId": "wf3kD9aB",
"reviewResult": null,
"metadata": {
"reason": "kyc-onboarding",
"channel": "mobile-app",
"department": "compliance"
},
"successUrl": "https://your-website.com/success",
"errorUrl": "https://your-website.com/error",
"supportUrl": "https://your-website.com/support",
"identityDocument": {
"type": "NATIONAL_ID",
"country": "ZM",
"serialNo": "9876543/21/1",
"nationalNo": "Z12345678",
"firstName": "Tisa",
"lastName": "Banda",
"dateOfBirth": "1997-05-10",
"placeOfBirth": "Lusaka",
"nationality": "ZM",
"expiryAt": "2032-05-09",
"issuedAt": "2022-05-10",
"issuingAuthority": "Republic of Zambia",
"placeOfIssue": "Lusaka",
"createdAt": "2025-08-20T09:31:00.000Z",
"updatedAt": "2025-08-20T10:15:00.000Z"
},
"faceScan": {
"ageEstimation": "OVER_25",
"createdAt": "2025-08-20T09:30:00.000Z",
"updatedAt": "2025-08-20T09:31:15.000Z"
},
"createdBy": "[email protected]",
"expiresAt": "2025-08-27T09:00:00.000Z",
"createdAt": "2025-08-20T09:00:00.000Z",
"updatedAt": "2025-08-20T10:15:00.000Z"
}
}