Building Didit Webhook Listeners with AWS Lambda & API Gateway

Secure Webhook IntegrationImplementing robust webhook signature verification using Didit's shared secret key is crucial for ensuring the integrity and authenticity of incoming data from Didit's platform, protecting against spoofing and tampering.

Scalable Serverless ArchitectureLeveraging AWS Lambda and API Gateway with the Serverless Framework provides a highly scalable and cost-effective solution for handling Didit webhook events, automatically adjusting to varying loads without manual intervention.

Real-time Identity WorkflowsProcessing Didit webhooks in real-time enables immediate responses to identity verification outcomes, facilitating dynamic user onboarding, fraud detection, and compliance actions, enhancing operational efficiency.

Didit's Developer-First ApproachDidit simplifies webhook management with clear API documentation, easy secret key rotation, and a modular architecture, allowing developers to quickly build and deploy custom event-driven workflows with Free Core KYC and no setup fees.

The Power of Webhooks in Identity Verification

In the world of identity verification, real-time feedback is paramount. Whether you're onboarding new users, conducting AML screening, or verifying age, knowing the outcome of a verification session as it happens allows for dynamic decision-making and seamless user experiences. This is where webhooks shine. Instead of constantly polling an API for status updates, Didit sends an automated notification to your specified endpoint whenever a significant event occurs, such as a verification session completing or a status changing. This push-based model is more efficient, reduces API call overhead, and ensures your systems are always up-to-date with the latest identity verification results.

Integrating Didit's powerful identity verification capabilities often involves setting up a reliable webhook listener. This listener acts as your application's eyes and ears, receiving critical updates about the status of ID Verification, Liveness Detection, or AML Screening outcomes. A well-implemented webhook system is a cornerstone of modern, event-driven architectures, providing the agility needed to respond swiftly to verification results and maintain a smooth user journey.

Setting Up Your Serverless Webhook Listener with AWS Lambda and API Gateway

Building a scalable and resilient webhook listener can be complex, but with AWS Lambda and API Gateway, coupled with the Serverless Framework, it becomes remarkably straightforward. This serverless approach means you don't have to manage any servers; AWS handles all the infrastructure, scaling your listener automatically based on demand. For our Didit webhook listener, we'll use TypeScript for type safety and developer productivity.

Prerequisites:

• An AWS account
• Node.js and npm installed
• Serverless Framework installed (npm install -g serverless)
• A Didit account with API keys and a webhook secret (from Didit Console -> Settings -> API Keys)

Project Setup:

First, create a new Serverless project:

serverless create --template aws-nodejs-typescript --path didit-webhook-listener
cd didit-webhook-listener
npm install

Now, let's configure serverless.yml to define our Lambda function and API Gateway endpoint:

service: didit-webhook-listener

provider:
  name: aws
  runtime: nodejs18.x
  stage: dev
  region: us-east-1
  environment:
    DIDIT_WEBHOOK_SECRET: ${ssm:/didit/webhook/secret}

functions:
  handleDiditWebhook:
    handler: src/handler.handleDiditWebhook
    events:
      - http:
          path: webhook/didit
          method: post
          cors: true

plugins:
  - serverless-offline
  - serverless-dotenv-plugin
  - serverless-ssm-fetch

Notice we're fetching the DIDIT_WEBHOOK_SECRET from AWS SSM Parameter Store, which is a best practice for managing secrets. You’ll need to store your Didit Webhook Secret there. Didit allows you to easily rotate your secret key via API or the Didit Console, ensuring good security hygiene.

Implementing Secure Webhook Processing in TypeScript

The most critical aspect of any webhook listener is security. You must verify that incoming requests genuinely originate from Didit and haven't been tampered with. Didit provides a shared secret key for this purpose, which you use to validate the HMAC signature included in the webhook's x-didit-signature header.

Create src/handler.ts:

import { APIGatewayProxyHandler } from 'aws-lambda';
import * as crypto from 'crypto';

const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET || '';

export const handleDiditWebhook: APIGatewayProxyHandler = async (event) => {
  if (!event.body) {
    return { statusCode: 400, body: 'No body received' };
  }

  const signature = event.headers['x-didit-signature'];
  if (!signature) {
    console.warn('Webhook received without x-didit-signature header.');
    return { statusCode: 403, body: 'Missing signature' };
  }

  try {
    const expectedSignature = crypto
      .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
      .update(event.body)
      .digest('hex');

    if (expectedSignature !== signature) {
      console.error('Webhook signature mismatch. Expected:', expectedSignature, 'Received:', signature);
      return { statusCode: 403, body: 'Invalid signature' };
    }

    const payload = JSON.parse(event.body);
    console.log('Successfully verified and parsed Didit webhook:', payload);

    // Implement your business logic here based on the webhook payload
    // Examples: update user status, trigger further actions, store results
    // For instance, if it's an ID Verification completion:
    // if (payload.event_type === 'session.completed' && payload.data.workflow_type === 'kyc') {
    //   console.log('KYC Session Completed for vendor_data:', payload.data.vendor_data);
    //   // Process KYC results, update user profile, etc.
    // }

    return { statusCode: 200, body: 'Webhook received and processed' };
  } catch (error) {
    console.error('Error processing webhook:', error);
    return { statusCode: 500, body: 'Internal server error' };
  }
};

In this code, we compute an HMAC SHA256 hash of the raw request body using your DIDIT_WEBHOOK_SECRET and compare it to the x-didit-signature header provided by Didit. If they don't match, the request is rejected, preventing unauthorized access or spoofed events. This robust verification process is essential for maintaining the security and integrity of your identity verification workflows, especially when dealing with sensitive data from Didit's ID Verification, Face Match, or AML Screening services.

Configuring Didit to Send Webhooks

Once your Lambda function is deployed and you have an API Gateway endpoint URL, the final step is to tell Didit where to send its webhooks. This can be done easily via the Didit Management API or through the Didit Business Console.

Via Didit Management API:

You can programmatically update your webhook configuration using the PATCH /v3/webhook/ endpoint. This allows you to set your webhook_url, specify a webhook_version (v3 is recommended), and even rotate your secret_shared_key securely.

curl -X PATCH https://verification.didit.me/v3/webhook/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_DIDIT_API_KEY" \
  -d '{
    "webhook_url": "YOUR_API_GATEWAY_ENDPOINT",
    "webhook_version": "v3"
  }'

Replace YOUR_DIDIT_API_KEY with your actual Didit API key and YOUR_API_GATEWAY_ENDPOINT with the URL provided by AWS API Gateway after deploying your Serverless function.

Via Didit Business Console:

Alternatively, navigate to the Didit Console, go to Settings -> Webhooks, and simply paste your API Gateway endpoint URL into the designated field. You can also view and rotate your webhook secret key here. Didit's modular design ensures that configuring these vital integrations is straightforward, allowing you to focus on building your core application.

How Didit Helps

Didit provides an AI-native, developer-first identity platform that makes integrating advanced identity verification simple and secure. Our modular architecture allows you to pick and choose the exact components you need, from ID Verification (OCR, MRZ, barcodes) and Passive & Active Liveness Detection to 1:1 Face Match, AML Screening & Monitoring, and Age Estimation. By offering Free Core KYC and no setup fees, Didit empowers businesses of all sizes to implement robust identity solutions without prohibitive costs.

Our comprehensive API documentation and instant sandbox environment ensure that developers can quickly get started, and our webhook system, as demonstrated, is designed for reliability and security. With Didit, you gain access to a global verification network, orchestrated workflows, and structured identity data, all delivered through clean APIs. This means you can confidently build custom webhook listeners that integrate seamlessly with Didit's powerful backend, ensuring real-time updates for all your identity verification needs.

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.