Verification data webhook
Requirements
- Setting up webhooks requires Admin role
- Setup webhooks
- A valid SSL certificate is required on your endpoint for TLS webhooks to prevent delivery failures.
Heads up
- For all webhook events, a non-
2xxresponse from your server triggers retry attempts to send a webhook from our system. In case of successful verification user will be redirected tofailedverification URL', without changing the actual verification status. - When setting up webhooks you will find legacy event
ID VERIFICATION, which receives all events. We recommend setting up separate events for better control. - Troubleshooting webhooks
Receiving Verification Results via Webhook
After a verification attempt concludes, an HTTP POST request containing the status and data is sent to your registered webhook endpoint.
Webhooks arrive at different times based on the verification flow and outcome. They generally fall into these categories:
Instant Webhooks (Automated)
- If your verification flow uses auto-review only, webhook arrives from event
ID VERIFICATION AUTO FINISHafter completion with status"final":True - Intermediate review results from auto-review, webhook arrives from event
ID VERIFICATION AUTO FINISHwith status"final":False - Canceled verifications from webhook event
ID VERIFICATION CANCELED
Prompt Webhooks (Manual)
The final status webhook arrives shortly after manual review is completed from event ID VERIFICATION MANUAL FINISH with status "final":True
Delayed Webhooks (On Expiry)
Webhooks are delayed until token or session expiry when:
- The client abandons verification before reaching maximum retries.
- The client never starts the session after token creation.
Understanding Delayed Webhooks & Expiry
- Delayed webhooks trigger upon
tokenExpiryorsessionLengthexpiration, based on your token generation settings. - If enough information is provided during verification process, they can still be verified.
- Otherwise handle these notifications as they signify incomplete or abandoned verifications.
iDenfy Verification Workflow
Webhook events
Flowchart represents the general flow, but events can be adjusted, skipped or ignored, depending on your needs.
Cancelation & Expiry
- If end-user at any point cancels the verification process, webhook event
ID VERIFICATION CANCELEDwill fire and no information will be processed - If the end user drops verification - closes the window, does not go through verification process in required time frame, etc, the
ID VERIFICATION EXPIREDwill fire:- If no or not enough information was uploaded before dropping verification, no processing will take place
- If all information was uploaded before dropping verification at least once, manual reviewers will review the verification.
Re-attempts
End-user will be prompted to re-take pictures or verification steps if there are issues. For example:
- Wrong selected country or document type
- Image quality low
- Face / document obscured
Re-attempt count
End-users have 1 overall re-attempt to make successful verification, and have 3 chances to reupload if images are sub-par Once there are no more attempts - processing continues with images already uploaded.
Callback structure
Parameters
JSON parameters you will find in the ID VERIFICATION webhook. For additional insight into what status means, visit vocabulary
Response example
This is an example JSON body in the callback HTTP request.
{
"final": true,
"platform": "PC",
"status": {
"overall": "APPROVED",
"suspicionReasons": [],
"denyReasons": [],
"fraudTags": [],
"mismatchTags": [],
"autoFace": "FACE_MATCH",
"manualFace": "FACE_MATCH",
"autoDocument": "DOC_VALIDATED",
"manualDocument": "DOC_VALIDATED",
"additionalSteps": "NOT_FOUND",
"amlResultClass": null,
"pepsStatus": null,
"sanctionsStatus": null,
"adverseMediaStatus": null
},
"data": {
"docFirstName": "MANFRED",
"docLastName": "WEBER",
"docNumber": "DE4878783",
"docPersonalCode": null,
"docExpiry": "2024-03-09",
"docDob": "1972-07-10",
"docDateOfIssue": "2014-03-09",
"docType": "PASSPORT",
"docSex": "MALE",
"docNationality": "NL",
"docIssuingCountry": "NL",
"birthPlace": "LONDON",
"authority": "BURG",
"address": null,
"docTemporaryAddress": null,
"mothersMaidenName": null,
"docBirthName": null,
"driverLicenseCategory": null,
"manuallyDataChanged": false,
"fullName": "MANFRED WEBER",
"selectedCountry": "NL",
"orgFirstName": "MANFRED",
"orgLastName": "WEBER",
"orgNationality": "NEDERLANDSE",
"orgBirthPlace": "LONDON",
"orgAuthority": "BURG",
"orgAddress": null,
"orgTemporaryAddress": null,
"orgMothersMaidenName": null,
"orgBirthName": null,
"ageEstimate": null,
"clientIpProxyRiskLevel": "VERY_LOW",
"duplicateFaces": null,
"duplicateDocFaces": null,
"additionalData": {
"UTILITY_BILL": {
"address": {
"status": "NO_DATA"
}
}
}
},
"fileUrls": {
"FACE": "https://s3.eu-west-1.amazonaws.com/production.users.storage/users_storage/users/eW_Dl8KdwpLCtsKlwqtywrHChcOXwrp0wqd4wp7DmsKXwpPCtMKpwqpywqnCrcKkwoZ4wqd4csKqwqBmwrU%3D/FACE.png?AWSAccessKeyId=AKIAJEE33B4FZLU73WMA&Signature=FLupfDktZyB4vbhYsSStIPvHV0o%3D&Expires=1700739964",
"FRONT": "https://s3.eu-west-1.amazonaws.com/production.users.storage/users_storage/users/eW_Dl8KdwpLCtsKlwqtywrHChcOXwrp0wqd4wp7DmsKXwpPCtMKpwqpywqnCrcKkwoZ4wqd4csKqwqBmwrU%3D/FRONT.png?AWSAccessKeyId=AKIAJEE33B4FZLU73WMA&Signature=FAJVUW99U4dkw4Ii85z%2BHpNd%2BsE%3D&Expires=1700739964",
"UTILITY_BILL": "https://s3.eu-west-1.amazonaws.com/production.users.storage/users_storage/users/eW_Dl8KdwpLCtsKlwqtywrHChcOXwrp0wqd4wp7DmsKXwpPCtMKpwqpywqnCrcKkwoZ4wqd4csKqwqBmwrU%3D/UTILITY_BILL.png?AWSAccessKeyId=AKIAJEE33B4FZLU73WMA&Signature=nZ0i5%2BJPzCDshWAgOj2HufZGtZs%3D&Expires=1700739964"
},
"additionalStepPdfUrls": {},
"AML": [
{
"status": {
"serviceSuspected": false,
"serviceUsed": true,
"serviceFound": true,
"checkSuccessful": true,
"overallStatus": "NOT_SUSPECTED"
},
"data": [
{
"name": null,
"surname": null,
"nationality": null,
"dob": null,
"suspicion": null,
"reason": null,
"listNumber": null,
"listName": null,
"score": null,
"lastUpdate": null,
"isPerson": null,
"isActive": null,
"checkDate": "2023-11-23 10:44:29"
}
],
"serviceName": "PilotApiAmlV2NameCheck",
"serviceGroupType": "AML",
"uid": "26b3ac22-89ed-11ee-ba61-0a201119565b",
"errorMessage": null
}
],
"LID": null,
"scanRef": "26b3ac22-89ed-11ee-ba61-0a201119565b",
"externalRef": null,
"clientId": "S53574N73T",
"startTime": 1700736224,
"finishTime": 1700736269,
"clientIp": "177.77.77.196",
"clientIpCountry": "LT",
"clientLocation": "Kaunas, Lithuania",
"manualAddress": null,
"manualAddressMatch": false,
"registryCenterCheck": null,
"addressVerification": null,
"questionnaireAnswers": null,
"companyId": null,
"beneficiaryId": null,
"riskAssessment": {
"risk_score": 38,
"risk_level": "MEDIUM"
},
"additionalSteps": {
"UTILITY_BILL": "COMPARE"
}
}
Webhook troubleshooting
Ensure that:
- You have provided a valid callback endpoint (it does not contain typos and is a fully specified URL with HTTP schema, port and domain name).
- The provided endpoint can be reached from the internet.
- Your SSL is set up correctly. Our system can only send webhooks to URLs with valid SSL certificates.
- You are truly not receiving a callback and your framework is not accidentally returning some other HTTP response e.g. 422 or 500.
Review webhooks sent via iDenfy dashboard
By going to Settings → Notifications → selecting Recently sent in the top right corner, you can search for specific notifications and see what was sent, and what status we received from your server.
-
Search field where you can use scanRef to search specific notifications for verification.
-
The response we received from your server:
0- No Response: No communication; server unreachable.2xx- Success: Request successful, information returned.3xx- Redirection: Further action needed, request redirected.4xx- Client Errors: Your servers couldn’t handle the response5xx- Server Errors: Request valid, there is a problem with the server
-
Date and time when notification was sent
-
Attempt to resend the webhook.
-
Shows full information of what was sent in JSON format.
