Skip to main content
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

1

Event Occurs

A verification process completes or changes status
2

Webhook Triggered

Urtentic prepares a webhook payload and cryptographically signs it
3

HTTP Request Sent

POST request sent to your configured endpoint
4

Response Processed

Your endpoint processes the event, responds, and retries if needed

Supported Events

Verification Lifecycle Events

Step-Specific Events

Webhook Payload Structure

Payload Fields

Base Event Fields

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

Step Completed Fields

Security & Authentication

Webhook Signatures

Every webhook payload is signed using HMAC-SHA256 with your webhook secret:

Signature Verification

Best Practices

  • Always verify signatures to ensure webhooks are from Urtentic
  • Check timestamps to prevent replay attacks
  • Use HTTPS endpoints for webhook URLs
  • Return appropriate HTTP status codes (200 for success)
  • Process webhooks idempotently using the event ID

Retry Policy

Urtentic automatically retries failed webhook deliveries:
Webhooks are considered failed if: non-2xx response, no response within 10 seconds, network error, or SSL error.

Webhook Configuration

Webhook Settings
Configure your webhook endpoints in the dashboard to receive real-time notifications about verification events.