Skip to main content

Events overview

k-ID provides two types of events to help you respond to user actions and system changes in real-time - DOM Events and Webhooks. Both event types allow you to build responsive integrations that react to important changes in the k-ID system.

What are events?​

Events are notifications sent by k-ID when specific actions occur in your application. They allow you to:

  • React to user actions: Respond immediately when users complete verification, grant consent, or interact with widgets
  • Update your application state: Keep your application synchronized with k-ID's state changes
  • Handle asynchronous operations: Receive notifications when long-running processes complete
  • Build real-time experiences: Create responsive user interfaces that update automatically

DOM events​

DOM Events are JavaScript events emitted by k-ID widgets that run in iframes on your website. These events are sent via the browser's postMessage API and can be listened to using standard JavaScript event listeners.

When to use DOM Events​

  • Responsive UI updates: To update your interface immediately when users interact with widgets
  • Client-side interactions: When you need to react to widget interactions in the browser
  • Real-time user feedback: To provide immediate visual feedback to users

Key features​

  • Emitted directly from widgets in iframes
  • Received via JavaScript message event listeners
  • Requires origin validation for security
  • Perfect for client-side JavaScript applications and responsive UI

For detailed information, see DOM Events.

Webhooks​

Webhooks are HTTP POST requests sent from k-ID's servers to your server endpoints. They provide server-to-server notifications about important events in the k-ID system.

When to use webhooks​

  • Data integrity: To reliably update your database and maintain data consistency
  • Server-side processing: When you need to handle events on your servers
  • Reliable delivery: For critical events that must be processed even if users navigate away
  • Background processing: To handle events asynchronously without blocking user interactions
  • State synchronization: To keep your server state synchronized with k-ID's state

Key features​

  • Sent as HTTP POST requests to your configured endpoints
  • Include cryptographic signatures for security validation
  • Configured per Product in Compliance Studio
  • Ideal for server-side integrations, data integrity, and reliable state management

For detailed information, see Webhooks.

Choosing between DOM events and webhooks​

Both event types serve different purposes and can be used together:

Use CaseRecommended Approach
Real-time UI updates in browserDOM Events
Data integrity and state managementWebhooks or server-side API calls
Server-side processing and database updatesWebhooks
Responsive user feedbackDOM Events
Reliable event processingWebhooks
Widget interactionsDOM Events
Best Practice

Use DOM Events for responsive UI updates, and use webhooks or server-side API calls (such as /age-verification/get-status or /challenge/get-status) for data integrity and reliable state management. Many applications use both, DOM Events for immediate UI feedback and webhooks for reliable server-side processing and data persistence.

Getting started​