Webhook Integration Guide: Real-Time Identity Verification

Real-Time UpdatesWebhooks provide immediate notifications on identity verification status changes, allowing for instant responses and improved user experience.

Enhanced SecuritySignature verification methods ensure the authenticity of webhook requests, protecting your application from malicious actors.

Flexible IntegrationMultiple signature headers accommodate various integration scenarios, ensuring compatibility with different web frameworks and middleware.

Simplified Workflows with DiditDidit's platform offers easy webhook configuration and comprehensive documentation, enabling developers to quickly integrate real-time identity verification notifications into their applications.

Understanding Webhooks in Identity Verification

Webhooks are a crucial component for building responsive and efficient identity verification workflows. They enable real-time communication between Didit's identity verification platform and your application, providing immediate updates on the status of verification sessions. Instead of constantly polling for updates, your application receives instant notifications when a session's status changes (e.g., from 'Not Started' to 'In Progress', or from 'In Review' to 'Approved'). This allows you to automate processes, improve user experience, and respond quickly to any issues.

For example, imagine a scenario where a user submits their ID for verification. Without webhooks, your application would need to periodically check the status of the verification. With webhooks, as soon as the verification is approved, your application receives a notification and can immediately grant the user access to the service. This reduces latency and provides a smoother, more seamless experience.

Configuring Webhooks for Didit's Identity Verification

Configuring webhooks with Didit is a straightforward process. First, you need to set up your team and application within the Didit platform. Then, navigate to your verification settings and enter your webhook URL. This URL is where Didit will send the real-time notifications. It's also essential to copy the Webhook Secret Key, which you'll use to validate incoming requests and ensure they are genuinely from Didit.

To ensure the security of your webhook endpoint, Didit provides multiple signature verification methods. These methods use a secret key to create a hash of the webhook payload, which you can then compare to the signature included in the webhook request. This ensures that the request is authentic and has not been tampered with. If you are using Cloudflare, you must whitelist Didit's IP address (18.203.201.92) to receive webhooks.

Signature Verification Methods: Ensuring Webhook Authenticity

Didit offers three signature headers to accommodate different integration scenarios:

• X-Signature: This signs the exact raw JSON bytes sent in the request body. It requires direct access to the raw request body before any parsing or re-encoding and may fail if middleware re-encodes Unicode characters differently.
• X-Signature-V2: The recommended method, it signs unescaped Unicode JSON. It works even if your middleware re-encodes the JSON, making it compatible with most web frameworks.
• X-Signature-Simple: This signs only core fields: "{timestamp}:{session_id}:{status}:{webhook_type}". It is completely independent of JSON encoding but does not verify the integrity of the decision or other fields.

We recommend trying X-Signature-V2 first, as it works even if your middleware re-encodes the JSON. If V2 fails, fall back to X-Signature-Simple. Use X-Signature only if you have direct access to the raw request bytes.

Webhook Event Types and Data Structure

Didit sends webhooks for the following event types:

• status.updated: Triggered whenever the verification status changes. This includes the initial webhook sent when a session starts.
• data.updated: Triggered when KYC or Proof of Address (POA) data is manually updated by a reviewer via the API. This allows you to stay in sync with data corrections or manual reviews.

Each webhook payload includes a webhook_type field indicating the event that triggered it. If the session status is Approved, Declined, In Review, or Abandoned, the webhook will also include a decision field containing detailed verification results. The session_id is always included, and the vendor_data, workflow_id, and metadata fields are included only if they are present in the session.

Handling Webhook Retries and Errors

If delivering a webhook fails (i.e., your endpoint returns a non-200 HTTP status code), Didit will retry the delivery up to five times with exponential backoff. After five failed attempts, the webhook will be dropped. It's crucial to ensure your webhook endpoint is reliable and can handle incoming requests promptly. You should also implement error logging and monitoring to identify and resolve any issues that may cause webhook delivery failures.

To avoid issues, ensure your server can handle the expected load of webhook events. Additionally, validate the webhook signature to confirm the authenticity of the request, and implement proper error handling to manage unexpected issues gracefully. By following these best practices, you can ensure a reliable and secure webhook integration with Didit's identity verification platform.

How Didit Helps

Didit simplifies the integration of real-time identity verification notifications through its user-friendly platform and comprehensive documentation. Didit’s identity verification suite, including ID Verification, Passive & Active Liveness, and AML Screening & Monitoring, is designed to be modular and easily integrated into existing systems.

Didit’s platform is AI-native, enabling advanced features and superior accuracy in identity verification. The flexible webhook configuration options and multiple signature verification methods ensure that your application receives secure and reliable real-time updates. Plus, with Didit’s Free Core KYC tier, you can start integrating webhooks and verifying identities without any setup fees.

Choose Didit as your identity verification provider and benefit from a developer-first approach, instant sandbox access, and clean APIs. Automate your workflows and improve your user experience with Didit's robust and scalable platform.

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.