Skip to main content
Webhooks let your server receive verification results automatically as soon as they are available. iDenfy sends an HTTP POST request to your configured endpoint with a JSON payload describing the verification outcome.

​
Prerequisites

1

Admin role required

You must have an Admin role in the iDenfy dashboard to configure webhook endpoints.
2

Configure your webhook endpoint

Go to Settings → Notifications → Webhook URLs in the dashboard and enter your callback URL.
3

Valid SSL certificate

Your endpoint must be served over HTTPS with a valid, non-self-signed SSL certificate.
If your endpoint does not return a 2xx HTTP status code, iDenfy will retry delivery. Make sure your endpoint responds with 200 OK promptly to avoid duplicate deliveries.
A legacy ID VERIFICATION event exists that fires for all verification outcomes in a single webhook. While still supported, we recommend subscribing to the individual events listed below for more predictable integration logic.

​
Webhook events and timing

Verification results arrive at different times depending on how the verification was processed. The table below summarises every event and when it fires.
EventTimingfinal flagDescription
ID VERIFICATION AUTO FINISHInstant (seconds)TrueAutomated review completed with a definitive result.
ID VERIFICATION AUTO FINISHInstant (seconds)FalseAutomated review completed but the result is preliminary — a manual review will follow.
ID VERIFICATION MANUAL FINISHPrompt (minutes)TrueA human reviewer has finalised the verification.
ID VERIFICATION CANCELEDVaries—The verification was canceled before completion.
ID VERIFICATION EXPIREDDelayed—The verification token or session expired before the user completed the flow.
Fires within seconds of the user completing the verification flow. The ID VERIFICATION AUTO FINISH event is sent with one of two final flag values:
  • final: True — the automated system reached a conclusive decision. No manual review will follow.
  • final: False — the automated system produced a preliminary result. A follow-up ID VERIFICATION MANUAL FINISH webhook will arrive once a human reviewer has made the final decision.
If you want to act only on definitive results, wait for a webhook where final is True.
When a verification requires human review, the ID VERIFICATION MANUAL FINISH event fires once the reviewer submits their decision. This always carries final: True.Manual reviews typically complete within minutes but may take longer during peak periods.
If the user never completes the verification and the token reaches its tokenExpiry or the session exceeds sessionLength, the ID VERIFICATION EXPIRED event fires automatically.
The ID VERIFICATION CANCELED event fires when a verification is explicitly canceled — either by the user abandoning the flow or by an API call.

​
Callback payload

For the full webhook callback JSON structure and field definitions, see the API Reference tab. The callback body includes overall status, document data, face-match results, fraud indicators, and extracted personal information.

​
Re-attempts and retries

iDenfy gives users a limited number of chances to submit acceptable documents:
  • 1 overall re-attempt — if the first verification is denied, the user may try once more with the same token.
  • Up to 3 chances for subpar images — if submitted photos are blurry, cropped, or unreadable, the user is prompted to re-capture up to 3 times before the attempt counts as failed.
Re-attempt limits are configurable per token at generation time. See Generate Token for details.

​
Handling the SUSPECTED status

A verification may return an overall status of SUSPECTED rather than a clear APPROVED or DENIED. This indicates the system found anomalies that require your attention. When you receive a SUSPECTED result, inspect the following fields in the callback payload:
FieldWhat to check
fraudTagsLists specific fraud indicators detected (e.g., digital tampering, screen capture).
mismatchTagsHighlights data inconsistencies between the document and submitted information.
documentStatusThe validation result for the submitted document itself.
faceStatusThe result of the face-match comparison between the selfie and document photo.
Build your business logic to handle SUSPECTED explicitly. Depending on your risk appetite, you may choose to approve, deny, or escalate these cases for manual internal review.

​
Troubleshooting

If you are not receiving webhooks, work through the following checklist:
1

Verify endpoint URL

Confirm the URL configured in the dashboard is correct, publicly reachable, and not behind a firewall or VPN.
2

Check SSL certificate

Your certificate must be valid and issued by a trusted CA. Self-signed certificates are rejected.
3

Return a 2xx response

Your endpoint must respond with a 2xx HTTP status code (e.g., 200 OK). Any other status triggers retries.
4

Review delivery logs

In the iDenfy dashboard, go to Settings → Notifications → Recently sent to inspect delivery attempts, response codes, and payloads.
If your endpoint consistently returns non-2xx responses, webhook delivery may be paused. Fix the underlying issue and check the dashboard logs to confirm delivery resumes.

​
Dashboard review

You can inspect all recently sent webhooks directly in the iDenfy dashboard:
  1. Navigate to Settings → Notifications → Recently sent.
  2. Review the list of delivered webhooks, including timestamps, HTTP response codes, and payload previews.
  3. Use this view to debug integration issues or confirm that specific verification results were delivered.