The Developer's Guide to Building Custom Webhook Listeners for KYC

Secure Webhook ConfigurationImplement secure webhook endpoints with HMAC-SHA256 signature verification and timestamp validation to prevent replay attacks and ensure data integrity from your KYC provider.

Real-time KYC ProcessingLeverage webhooks to receive instant notifications on identity verification session status, enabling immediate updates to user profiles and streamlining onboarding workflows.

Robust Error HandlingDesign your webhook listener with comprehensive error handling, including retries and dead-letter queues, to manage transient issues and ensure no critical KYC data is lost.

Didit's Streamlined IntegrationDidit simplifies webhook setup with clear API documentation, configurable versions, and automatic secret rotation, making it easy to integrate real-time KYC results securely and efficiently into any application.

The Power of Real-time KYC with Webhooks

In today's fast-paced digital economy, real-time identity verification (KYC) is no longer a luxury but a necessity. Businesses need to onboard users quickly and securely, instantly verifying their identities to prevent fraud and comply with regulations. While polling an API for status updates can work, it's inefficient and can introduce delays. This is where webhooks shine. Webhooks provide an instant, event-driven mechanism for your KYC provider to notify your application whenever a verification session's status changes. This enables immediate decision-making, faster user onboarding, and a superior customer experience.

For developers, building a custom webhook listener means taking control of your KYC workflow. Instead of waiting, your system reacts. Whether it's a successful ID Verification, a failed Liveness check, or an AML Screening alert, webhooks deliver the information you need precisely when you need it. Didit, with its AI-native platform, embraces this real-time paradigm, offering robust webhook capabilities that integrate seamlessly into your existing infrastructure.

Configuring Your Webhook Endpoint with Didit

Setting up your webhook endpoint with a provider like Didit is straightforward. Didit allows you to configure your webhook URL, specify the payload version (v3 is recommended for the latest features), and manage your secret key directly through its API or Business Console. This flexibility ensures you can tailor the integration to your specific needs.

When configuring, you'll define the URL where Didit will send notifications. This URL must be publicly accessible and capable of receiving POST requests. Didit also allows you to set a data_retention_months parameter, giving you control over how long session data is stored, which is crucial for compliance. You can also specify the capture_method for verification sessions (mobile, desktop, or both) and even rotate your secret_shared_key for enhanced security, invalidating the old key immediately.

For instance, using Didit's management API, you can update your webhook configuration:

PATCH /v3/webhook/
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "capture_method": "both",
  "data_retention_months": 12
}

This simple API call tells Didit where to send your real-time KYC updates and how to format them, ensuring you receive critical information for processes like ID Verification and Passive & Active Liveness checks.

Building a Secure and Reliable Webhook Listener

Security is paramount when handling sensitive KYC data. Your webhook listener must be designed to verify the authenticity and integrity of every incoming request. Didit provides a secret_shared_key that you'll use to validate webhook signatures. The process typically involves:

1. Receiving the Request: Your endpoint receives a POST request from Didit.
2. Extracting the Signature: Didit includes an X-Signature header with an HMAC-SHA256 signature.
3. Verifying the Signature: You'll compute your own HMAC-SHA256 signature using the raw request body and your secret_shared_key. This computed signature must match the one in the X-Signature header. Crucially, do NOT parse the JSON body before verifying the signature.
4. Timestamp Validation: Webhook payloads also include a timestamp. Validate that this timestamp is recent (e.g., within 5 minutes) to prevent replay attacks.
5. Processing the Payload: Once verified, you can safely parse the JSON body and process the KYC results.

Beyond security, reliability is key. Your listener should be idempotent, meaning processing the same event multiple times has the same effect as processing it once. Implement robust error handling, including logging, retries for transient failures, and potentially a dead-letter queue for events that consistently fail processing. This ensures that critical identity verification results, including those from AML Screening & Monitoring or Age Estimation, are never missed.

Handling Webhook Events and Integrating with Your Core Logic

Once you've securely received and validated a webhook event, the next step is to integrate it with your application's core logic. Didit's webhooks provide detailed information about the verification session, including its status (e.g., approved, rejected, pending), the reason for the status, and relevant data points. For example, a successful ID Verification event might trigger an update to a user's profile, marking them as verified and unlocking access to certain features.

Consider the types of events you might receive:

• Session Completed: The most common event, indicating a verification session has reached a final state (approved, rejected, or manual review).
• Document Verified: Specific to ID Verification, confirming document authenticity.
• Liveness Check Passed/Failed: Crucial for fraud prevention, indicating the outcome of a Liveness check.
• AML Alert: Signifies a hit during AML Screening, requiring further investigation.

Your listener should parse these events and trigger appropriate actions within your system. This could involve updating a user's status in your database, sending internal notifications, or initiating further steps in a multi-stage onboarding workflow. Didit's modular architecture means these events can feed directly into your orchestrated workflows, allowing for dynamic reactions to verification outcomes.

How Didit Helps

Didit is engineered to simplify the complex world of identity verification, and its webhook system is a prime example. As an AI-native, developer-first platform, Didit provides clean APIs and comprehensive documentation that make integrating webhooks a breeze. We offer Free Core KYC, allowing you to get started without upfront costs, and our modular architecture means you only use and pay for what you need.

With Didit, you benefit from:

• Seamless Configuration: Easily set up and manage your webhook URL, version, and secret key through the API or the intuitive Business Console.
• Robust Security Features: Built-in support for HMAC-SHA256 signature verification and timestamp validation ensures the integrity and authenticity of all incoming webhook data.
• Detailed Payloads: Receive rich, structured data for every verification event, covering products like ID Verification, Passive & Active Liveness, 1:1 Face Match, AML Screening & Monitoring, Proof of Address, and Age Estimation.
• Orchestrated Workflows: Webhook events can seamlessly integrate into Didit's no-code workflow builder, allowing you to design sophisticated, automated responses to verification outcomes.
• No Setup Fees: Get started immediately and integrate powerful identity verification capabilities into your application without hidden costs.

Didit's commitment to being developer-first means you spend less time on integration boilerplate and more time building innovative features, all while ensuring your KYC processes are secure, compliant, and lightning-fast.

Ready to Get Started?

Ready to see Didit in action? Get a free demo today.

Start verifying identities for free with Didit's free tier.