Skip to main content

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- 2xx response from your server triggers retry attempts to send a webhook from our system. In case of successful verification user will be redirected to failed 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.
Understanding Delayed Webhooks & Expiry
  • Delayed webhooks trigger upon tokenExpiry or sessionLength 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.

Cancellation & 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
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.

Handling SUSPECTED status​

understanding suspicion status

A SUSPECTED status doesn't mean automatic failure. Always check the document (manualDocument) and face (manualFace) statuses too (e.g., for DOC_VALIDATED, FACE_MATCH), as they might still be approved.

  • If a webhook's overall status is SUSPECTED, check the fraudTags and mismatchTags lists (in the status object) for specific reasons.
  • Use fraudTags and mismatchTags in combination with document/face validation results to decide whether to onboard the user.
  • Important: Prepare your system to handle new, unexpected tag values appearing in the future.
flowchart explanation how webhook response works

Callback structure​

Identification Webhook

This notification is sent when a client completes an identity verification. Legacy, use ID_VERIFICATION_AUTO_FINISHED, ID_VERIFICATION_MANUAL_FINISHED, ID_VERIFICATION_EXPIRED and ID_VERIFICATION_CANCELLED instead.

Find info about webhook signing here.
header Parameters
Idenfy-Event-Type
required
string
Value: "IDENTIFICATION"
Idenfy-Signature
string

Webhook signature

Request Body schema: application/json
required
final
required
boolean
platform
required
string (DeviceTypeEnum)
Enum: "PC" "MOBILE" "TABLET" "MOBILE_APP" "MOBILE_SDK" "OTHER"
required
object (IdentificationStatusWebhook)
required
object (IdentificationDataWebhook)
required
object or null
object or null
Array of any or null (AmlResults)
object or null
Array of objects or null (LidResults)
Array of objects or null (CriminalCheckResults)
scanRef
required
string <= 36 characters
externalRef
string or null <= 40 characters
clientId
required
string <= 100 characters
companyId
required
string <= 36 characters
beneficiaryId
required
string <= 36 characters
startTime
required
integer
finishTime
required
integer
clientIp
required
string or null <= 39 characters
clientIpCountry
required
string or null <= 2 characters
clientLocation
required
string or null <= 100 characters
gdcMatch
boolean or null
manualAddress
string or null <= 255 characters
manualAddressMatch
boolean
any or null
object or null
object or null
object or null
object or null
object or null
object or null
object or null
object or null

Responses

Request samples

Content type
application/json
{
  • "final": true,
  • "platform": "PC",
  • "status": {
    },
  • "data": {
    },
  • "fileUrls": {
    },
  • "additionalStepPdfUrls": {
    },
  • "AML": [
    ],
  • "amlCheck": {
    },
  • "LID": [
    ],
  • "CRIMINAL_CHECK": [
    ],
  • "scanRef": "string",
  • "externalRef": "string",
  • "clientId": "string",
  • "companyId": "string",
  • "beneficiaryId": "string",
  • "startTime": 0,
  • "finishTime": 0,
  • "clientIp": "string",
  • "clientIpCountry": "st",
  • "clientLocation": "string",
  • "gdcMatch": true,
  • "manualAddress": "string",
  • "manualAddressMatch": true,
  • "registryCenterCheck": {
    },
  • "addressVerification": {
    },
  • "questionnaireAnswers": {
    },
  • "riskAssessment": {
    },
  • "bankVerification": {
    },
  • "emailVerification": {
    },
  • "phoneVerification": {
    },
  • "driverLicenseCheck": {
    },
  • "additionalSteps": {
    }
}

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.

  1. Search field where you can use scanRef to search specific notifications for verification.

  2. 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 response
    • 5xx - Server Errors: Request valid, there is a problem with the server

  3. Date and time when notification was sent

  4. Attempt to resend the webhook.

  5. Shows full information of what was sent in JSON format.

Token generation UML activity diagram