Verification data webhook
- Setting up webhooks requires Admin role
- Setup webhooks
- A valid SSL certificate is required on your endpoint for TLS webhooks to prevent delivery failures.
- For all webhook events, a non-
2xx
response from your server triggers retry attempts to send a webhook from our system. In case of successful verification user will be redirected tofailed
verification 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 FINISH
after completion with status"final":True
- Intermediate review results from auto-review, webhook arrives from event
ID VERIFICATION AUTO FINISH
with 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.
- Delayed webhooks trigger upon
tokenExpiry
orsessionLength
expiration, 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 CANCELED
will 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 EXPIRED
will 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
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
final
| Type: Bool
Indicates if this callback is likely the final one for the verification.
If true
, it's the final callback unless manually reviewed again.
If false
and webhooks are set up, expect another callback.
platform
| Type: String
Identifies the platform used to complete the verification. Possible values: PC
, MOBILE
, TABLET
, MOBILE_APP
, MOBILE_SDK
, OTHER
Max length 30
status
| Type: Object
Dictionary containing the detailed verification status breakdown.
—
overall
| Type: String
Overall status of the verification. It depends on auto or manual webhook, but if face status: autoFace
, manualFace
is FACE_MATCH
and document status autoDocument
, manualDocument
is DOC_VALIDATED
, then the verification is approved. If other statuses exist, for example: DOC_NOT_FOUND
, FACE_MISMATCH
, then verification is declined. If any fraudTags or mismatchTags exist for the verification, then status can be set as SUSPECTED
, because the identification caught some discrepancies. If verification is approved(FACE_MATCH
and DOC_VALIDATED
) but overall status SUSPECTED it should be decided on your end to allow or decline this client. Possible values:
APPROVED
DENIED
SUSPECTED
EXPIRED
Max length 30
fraudTags
| Type: List
A list of fraud tags (strings) indicating why the verification was marked as SUSPECTED
. Possible values:
FACE_SUSPECTED
FACE_BLACKLISTED
DOC_FACE_BLACKLISTED
DOC_MOBILE_PHOTO
DEV_TOOLS_OPENED
DOC_PRINT_SPOOFED
FAKE_PHOTO
AML_SUSPECTION
AML_FAILED
LID_SUSPECTION
LID_FAILED
RC_FAILED
UTILITY_ADDRESS_CHECK_FAILURE
VIRTUAL_CAMERA
FACE_IN_BLACKLIST
DOC_FACE_IN_BLACKLIST
DUPLICATE_FACE
DUPLICATE_DOC_FACE
CRIMINAL_SUSPECTED
CRIMINAL_CHECK_FAILED
RC_FAILED
DL_FAILED
—
mismatchTags
| Type: List
A list of mismatch tags indicating data mismatches between the document and the partner's provided info. Triggers SUSPECTED
status. Possible values:
NAME
SURNAME
DOCUMENT_NUMBER
PERSONAL_CODE
EXPIRY_DATE
DATE_OF_BIRTH
DATE_OF_ISSUE
FULL_NAME
UNDER_AGE
OVER_AGE
UNKNOWN_AGE
SEX
NATIONALITY
INVALID_ADDITIONAL_STEP
ADDITIONAL_STEP_NOT_FOUND
DOC_INFO_MISMATCH
ADDITIONAL_STEP_INFORMATION_MISMATCH
EXPIRED_ADDITIONAL_STEP_INFORMATION
REGISTRY_CENTER_INFO_MISMATCH
DRIVER_LICENSE_INFO_MISMATCH
—
autoFace
| Type: String
Automated face analysis result returned by the system. Possible values:
FACE_MATCH
FACE_MISMATCH
NO_FACE_FOUND
TOO_MANY_FACES
FACE_TOO_BLURRY
FACE_GLARED
FACE_UNCERTAIN
FACE_NOT_ANALYSED
FACE_NOT_CHECKED
FACE_ERROR
AUTO_UNVERIFIABLE
FAKE_FACE
null
Max length 30
manualFace
| Type: String
Final face analysis result based on both automated and manual verification. Possible values:
FACE_MATCH
FACE_MISMATCH
NO_FACE_FOUND
TOO_MANY_FACES
FACE_TOO_BLURRY
FACE_GLARED
FACE_UNCERTAIN
FACE_NOT_ANALYSED
FACE_NOT_CHECKED
FACE_ERROR
AUTO_UNVERIFIABLE
FAKE_FACE
null
Max length 30
autoDocument
| Type: String
Automatic document analysis result provided by the system. Possible values:
DOC_VALIDATED
DOC_INFO_MISMATCH
DOC_NOT_FOUND
DOC_NOT_FULLY_VISIBLE
DOC_NOT_SUPPORTED
DOC_FACE_NOT_FOUND
DOC_TOO_BLURRY
DOC_GLARED
DOC_FACE_GLARED
MRZ_NOT_FOUND
MRZ_OCR_READING_ERROR
BARCODE_NOT_FOUND
DOC_EXPIRED
COUNTRY_MISMATCH
DOC_TYPE_MISMATCH
DOC_SIDE_MISMATCH
DOC_DAMAGED
DOC_FAKE
DOC_ERROR
AUTO_UNVERIFIABLE
DOC_NOT_ANALYSED
DOC_NAME_ERROR
DOC_SURNAME_ERROR
DOC_EXPIRY_ERROR
DOC_DOB_ERROR
DOC_PERSONAL_NUMBER_ERROR
DOC_NUMBER_ERROR
DOC_DATE_OF_ISSUE_ERROR
DOC_SEX_ERROR
DOC_NATIONALITY_ERROR
COUNTRY_NOT_SUPPORTED
DOC_PERSONAL_CODE_INVALID
DOC_SPOOF_DETECTED
MRZ_INVALID
DOC_NOT_ALLOWED
NFC_INIT_FAILED
NFC_FAILLED
NFC_TIMEOUT
Max length 30
manualDocument
| Type: String
Final document analysis result based on both automated and manual review. Possible values:
DOC_VALIDATED
DOC_INFO_MISMATCH
DOC_NOT_FOUND
DOC_NOT_FULLY_VISIBLE
DOC_NOT_SUPPORTED
DOC_FACE_NOT_FOUND
DOC_TOO_BLURRY
DOC_GLARED
DOC_FACE_GLARED
MRZ_NOT_FOUND
MRZ_OCR_READING_ERROR
BARCODE_NOT_FOUND
DOC_EXPIRED
COUNTRY_MISMATCH
DOC_TYPE_MISMATCH
DOC_SIDE_MISMATCH
DOC_DAMAGED
DOC_FAKE
DOC_ERROR
AUTO_UNVERIFIABLE
DOC_NOT_ANALYSED
DOC_NAME_ERROR
DOC_SURNAME_ERROR
DOC_EXPIRY_ERROR
DOC_DOB_ERROR
DOC_PERSONAL_NUMBER_ERROR
DOC_NUMBER_ERROR
DOC_DATE_OF_ISSUE_ERROR
DOC_SEX_ERROR
DOC_NATIONALITY_ERROR
COUNTRY_NOT_SUPPORTED
DOC_PERSONAL_CODE_INVALID
DOC_SPOOF_DETECTED
MRZ_INVALID
DOC_NOT_ALLOWED
NFC_INIT_FAILED
NFC_FAILLED
NFC_TIMEOUT
Max length 30
additionalSteps
| Type: String
Result of any additional steps taken for verification (usually manual). Possible values:
VALID
INVALID
NOT_FOUND
Max length 30
data
| Type: Object
Dictionary containing parsed data from the client's identity document and other verification details.
—
docFirstName
| Type: String
Client's name parsed from the document.
Max length 100
docLastName
| Type: String
Client's surname parsed from the document.
Max length 100
docNumber
| Type: String
Client's document number parsed from the document.
Max length 100
docPersonalCode
| Type: String
Client's personal code parsed from the document.
Max length 15
docExpiry
| Type: String
Client's document expiry date parsed from the document.
Max length 100
docDob
| Type: String
Client's date of birth parsed from the document.
Max length 100
docDateOfIssue
| Type: String
Client's document issue date parsed from the document.
Max length 100
docType
| Type: String
Client's document type used to complete the verification. Possible values:
ID_CARD
PASSPORT
RESIDENCE_PERMIT
DRIVER_LICENSE
PAN_CARD
AADHAAR
VISA
NATIONAL_PASSPORT
PROVISIONAL_DRIVER_LICENSE
OLD_ID_CARD
MILITARY_CARD
BANK_ID_SE
ADDRESS_CARD
Max length 30
docSex
| Type: String
Client's sex parsed from the document. Possible values:
MALE
FEMALE
UNDEFINED
Max length 9
docNationality
| Type: String
Client's nationality parsed from the document.
Country alpha-2
code
docIssuingCountry
| Type: String
Client's document issuing country parsed from the document.
Country alpha-2
code
docTemporaryAddress
| Type: String
Client's temporary address parsed from the document.
Max length 100
docBirthName
| Type: String
Client's birth name parsed from the document.
Max length 100
docPatronymic
| Type: String
Client's father's name parsed from the document.
Max length 100
birthPlace
| Type: String
Client's birthplace parsed from the document.
Max length 60
authority
| Type: String
The authority of the document parsed from the document.
Max length 60
address
| Type: String
Client's address parsed from the document.
Max length 100
mothersMaidenName
| Type: String
Client's mother's maiden name parsed from the document.
Max length 80
driverLicenseCategory
| Type: String
Client's driving license categories (classes) parsed from the document.
Max length 30
manuallyDataChanged
| Type: Bool
Indicates whether a manual reviewer has changed any parsed data from the document. Only true
in manual reviews.
—
fullName
| Type: String
Client's full name parsed from the document.
Max length 201
selectedCountry
| Type: String
Country selected during the verification process.
Any country in alpha-2
code
orgFirstName
| Type: String
Client's name parsed in the original language.
Max length 255
orgLastName
| Type: String
Client's surname parsed in the original language.
Max length 255
orgNationality
| Type: String
Client's nationality parsed in the original language.
Max length 255
orgBirthPlace
| Type: String
Client's birthplace parsed in the original language.
Max length 500
orgAuthority
| Type: String
Client's document authority parsed in the original language.
Max length 500
orgAddress
| Type: String
Client's address parsed in the original language.
Max length 500
orgTemporaryAddress
| Type: String
Client's temporary address parsed in the original language.
Max length 500
orgMothersMaidenName
| Type: String
Client's mother's maiden name parsed in the original language.
Max length 500
orgPatronymic
| Type: String
Client's father's name parsed in the original language.
Max length 500
orgBirthName
| Type: String
Client's birth name parsed in the original language.
Max length 500
ageEstimate
| Type: String
Client's estimated age from the selfie (when liveness is on). Possible values:
UNDER_13
OVER_13
OVER_18
OVER_22
OVER_25
OVER_30
Max length 10
clientIpProxyRiskLevel
| Type: String
Client's IP proxy risk level. null
if feature not enabled or verification is not APPROVED
. Possible values:
VERY_LOW
LOW
MEDIUM
HIGH
VERY_HIGH
NOT_CHECKED
Max length 11
duplicateFaces
| Type: List
ScanRefs
of other clients whose selfie matched this one. null
if empty.
—
duplicateDocFaces
| Type: List
ScanRefs
of other clients whose document face matched this one. null
if empty.
—
additionalData
| Type: JSON object
Additional data provided alongside any additionalSteps
. For example, Social Security Number in UTILITY_BILL
.
Must be used with additionalSteps
fileUrls
| Type: Object
Dictionary containing URLs to download or view verification photos and videos.
—
FRONT
| Type: String
A URL to download front document side photo with which a client has completed a verification.
—
BACK
| Type: String
A URL to download back document side photo with which a client has completed a verification.
—
FACE
| Type: String
A URL to download face photo with which a client has completed a verification.
—
FRONT_VIDEO
| Type: String
A URL to download the video of a client taking the front photo.
—
BACK_VIDEO
| Type: String
A URL to download the video of a client taking the back photo.
—
FACE_VIDEO
| Type: String
A URL to download the video of a client taking the face photo.
—
ADDITIONAL_DOCUMENT
| Type: String
A URL to download additional document front side photo.
—
ADDITIONAL_DOCUMENT_BACKSIDE
| Type: String
A URL to download additional document backside side photo.
—
ADDITIONAL_DOCUMENT_VIDEO
| Type: String
A URL to download the video of a client taking the additional document front side photo.
—
ADDITIONAL_DOCUMENT_BACKSIDE_VIDEO
| Type: String
A URL to download the video of a client taking the additional document backside side photo.
—
AML
| Type: List
Contains AML
service data, if enabled.
Refer to AML
documentation.
LID
| Type: List
Contains Lost-Invalid-Documents (LID
) service data, if enabled.
Refer to LID
documentation.
scanRef
| Type: String
Unique string to trace back a verification in iDenfy’s system.
Max length 36
externalRef
| Type: String
Unique string to link the client externally to iDenfy system.
Max length 40
clientId
| Type: String
Unique identifier for the client on your system.
Max length 100
startTime
| Type: Int
Timestamp when the client started the verification process.
—
finishTime
| Type: Int
Timestamp when the final automatic decision was made.
—
clientIp
| Type: String
Client's IP address.
Max length 39
clientIpCountry
| Type: String
Country alpha-2
code based on client's IP address.
Country alpha-2
code
clientLocation
| Type: String
Detailed location info based on IP.
Max length 100
manualAddress
| Type: String
Parsed address from utility bill if uploaded.
—
manualAddressMatch
| Type: Bool
Indicates if address from document matched the partner's provided address after manual review.
—
additionalStepPdfUrls
| Type: Object
Contains URLs to download uploaded PDF
documents from additional verification steps.
Example: "UTILITY_BILL
": "https://..."
addressVerification
| Type: JSON object
Address verification details.
null
if feature not enabled or not final callback with manualAddressMatch
true
registryCenterCheck
| Type: JSON object
Registry center check details.
null
if feature not enabled
questionnaireAnswers
| Type: JSON object
Client's questionnaire answers.
null
if feature not enabled or questionnaire not used
companyId
| Type: String
Company ID from KYB
form related to this verification.
null
if not KYB
related
beneficiaryId
| Type: String
Beneficiary ID from KYB
form related to this verification.
null
if not KYB
related
additionalSteps
| Type: JSON object
Custom additional step name and method used.
null
if no custom additional steps
riskAssessment
| Type: JSON object
Risk score and level if RA
profile used.
null
if RA
profile not used
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.
