Webhooks are HTTP POST requests that Urtentic sends to your application when specific events occur during the verification process. Instead of continuously checking the API for updates, your application receives instant notifications when verification statuses change.
Key Benefits
Real-time Updates Instant notifications when verifications complete or fail without API polling
Secure & Reliable Cryptographically signed payloads with automatic retry mechanism
Comprehensive Events Verification lifecycle events, step completion, and error notifications
Selective Notifications Choose which events to receive and filter by verification types
How Webhooks Work
Event Occurs
A verification process completes or changes status
Webhook Triggered
Urtentic prepares a webhook payload and cryptographically signs it
HTTP Request Sent
POST request sent to your configured endpoint
Response Processed
Your endpoint processes the event, responds, and retries if needed
Supported Events Verification Lifecycle Events Event Type Description When Triggered verification_startedNew verification started When POST /verifications is called verification_inputs_completedUser submitted inputs When inputs are successfully submitted verification_completedVerification finished When verification reaches final status verification_data_updatedData updated When document data is manually updated verification_abandonedVerification abandoned When verification is marked stale (>24 hours)
Step-Specific Events Event Type Description Process Types step_completedIndividual step completed DOCUMENT_VERIFICATION, LIVENESS, EMAIL_CHECK, LOCATION_INTELLIGENCE, WATCHLIST_CHECK, VIDEO_AGREEMENT
Webhook Payload Structure Verification Completed
Step Completed
Other Events
{ "eventName" : "verification_completed" , "flowId" : "wf_789012ghi345" , "timeStamp" : "2023-12-01T15:30:00.000Z" , "resource" : "/api/v1/verifications/id_jkl678mno901" , "metadata" : { "userId" : "user_12345" , "reference" : "REF-67890" }, "verificationStatus" : "SUCCESS" }
{ "eventName" : "step_completed" , "flowId" : "wf_789012ghi345" , "timeStamp" : "2023-12-01T15:25:00.000Z" , "resource" : "/api/v1/verifications/id_jkl678mno901" , "metadata" : { "userId" : "user_12345" }, "id" : "step_document_verification" , "status" : 200 , "data" : { "extractedData" : { "firstName" : "John" , "lastName" : "Smith" , "documentType" : "PASSPORT" } }, "step" : { "stepId" : "document_verification" , "status" : 200 , "startedAt" : "2023-12-01T15:20:00" , "completedAt" : "2023-12-01T15:25:00" } }
Verification Abandoned: { "eventName" : "verification_abandoned" , "flowId" : "wf_789012ghi345" , "timeStamp" : "2023-12-02T15:30:00.000Z" , "resource" : "/api/v1/verifications/id_jkl678mno901" , "metadata" : { "userId" : "user_12345" }, "verificationStatus" : "ABANDONED" }
Verification Started: { "eventName" : "verification_started" , "flowId" : "wf_789012ghi345" , "timeStamp" : "2023-12-01T14:00:00.000Z" , "resource" : "/api/v1/verifications/id_jkl678mno901" , "metadata" : { "userId" : "user_12345" , "reference" : "REF-67890" } }
Verification Inputs Completed: { "eventName" : "verification_inputs_completed" , "flowId" : "wf_789012ghi345" , "timeStamp" : "2023-12-01T15:00:00.000Z" , "resource" : "/api/v1/verifications/id_jkl678mno901" , "metadata" : { "userId" : "user_12345" } }
Payload Fields Base Event Fields Field Type Description eventNamestring Event type identifier flowIdstring UUID of the workflow timeStampstring ISO 8601 timestamp resourcestring API resource path to the verification metadataobject Custom metadata provided during verification creation
The metadata object is completely flexible and defined by your application. Common fields include userId, reference, deviceId, sessionId, etc. This metadata is echoed back in all webhook notifications to help you correlate events with your users.
Verification Completed Fields Field Type Description verificationStatusstring Final status (SUCCESS, REJECTED, NEEDS_REVIEW, ABANDONED)
Step Completed Fields Field Type Description idstring Step identifier statusnumber HTTP status code (200 for success) dataobject Step-specific extracted data stepobject Detailed step information including timing and results
Security & Authentication Webhook Signatures Every webhook payload is signed using HMAC-SHA256 with your webhook secret:
POST /webhook HTTP / 1.1 Host : yourapp.com Content-Type : application/json x-urtentic-signature : 5d41402abc4b2a76b9719d911017c592 x-urtentic-timestamp : 1701439800
Signature Verification const crypto = require ( 'crypto' ); function verifyWebhookSignature ( payload , signature , secret , timestamp ) { const currentTime = Math . floor ( Date . now () / 1000 ); if ( Math . abs ( currentTime - timestamp ) > 300 ) { throw new Error ( 'Webhook timestamp too old' ); } const secretBytes = Buffer . from ( secret , 'base64' ); const expectedSignature = crypto . createHmac ( 'sha256' , secretBytes ) . update ( payload , 'utf8' ) . digest ( 'hex' ); if ( signature . startsWith ( 'sha256=' )) { signature = signature . substring ( 7 ); } if ( ! crypto . timingSafeEqual ( Buffer . from ( signature , 'hex' ), Buffer . from ( expectedSignature , 'hex' ) )) { throw new Error ( 'Webhook signature verification failed' ); } return true ; }
Best Practices
Always verify signatures to ensure webhooks are from UrtenticCheck timestamps to prevent replay attacksUse HTTPS endpoints for webhook URLsReturn appropriate HTTP status codes (200 for success)Process webhooks idempotently using the event ID
Retry Policy Urtentic automatically retries failed webhook deliveries:
Retry Delay Initial After 1 minute Second After 5 minutes Third After 15 minutes Fourth After 1 hour Final After 6 hours
Webhooks are considered failed if: non-2xx response, no response within 10 seconds, network error, or SSL error.
Webhook Configuration Configure your webhook endpoints in the dashboard to receive real-time notifications about verification events. 
