Securing Webhooks with Signature Verification for Identity Workflows

Webhook signature verification is a critical security measure that ensures the integrity and authenticity of real-time notifications sent from an identity verification provider to your application.

When dealing with sensitive identity data and crucial fraud signals, verifying the origin and content of every webhook payload is non-negotiable. Without proper webhook signature verification, your application is vulnerable to replay attacks, data tampering, and unauthorized data injection, which can lead to severe security breaches and undermine the reliability of your identity and fraud infrastructure.

Why Webhook Security is Paramount for Identity and Fraud

Identity verification (User Verification / KYC - Know Your Customer, Business Verification / KYB - Know Your Business) and fraud detection (Transaction Monitoring, Wallet Screening / KYT - Know Your Transaction) rely on timely and accurate data exchange. Webhooks are the backbone of many such systems, providing instant updates on verification status, risk scores, or suspicious activities. However, this real-time communication channel introduces potential vulnerabilities if not properly secured.

Imagine a scenario where a malicious actor intercepts a webhook notification about a successful identity verification. Without webhook signature verification, they could alter the payload to show a failed verification or even inject a fraudulent success notification. This could lead to:

• Unauthorized account openings: If a fraudster can spoof a "verified" status, they could bypass your onboarding checks.
• Missed fraud alerts: Tampered webhooks could hide critical signals about risky transactions or suspicious wallet activity.
• Data integrity issues: Incorrect or manipulated data flowing into your system can corrupt your records and lead to erroneous decisions.

Therefore, implementing reliable webhook signature verification is not just a best practice; it's a fundamental requirement for maintaining the security and trustworthiness of your identity and fraud infrastructure.

How Webhook Signature Verification Works

At its core, webhook signature verification involves a shared secret and a cryptographic hash function. Here's a simplified breakdown of the process:

1. Shared Secret: Both your application and the webhook sender (e.g., an identity verification provider like Didit) agree on a secret key. This key should be unique, strong, and kept confidential.
2. Payload Hashing: Before sending a webhook, the provider takes the raw request body (payload) and combines it with the shared secret. This combined string is then run through a cryptographic hash function (e.g., HMAC-SHA256).
3. Signature Generation: The output of the hash function is the digital signature. This signature is typically sent as part of a header in the webhook request (e.g., X-Didit-Signature).
4. Verification on Receipt: When your application receives the webhook, it performs the same hashing process: it takes the raw payload from the request body, combines it with its copy of the shared secret, and hashes it using the exact same algorithm.
5. Comparison: Your application then compares the generated hash with the signature provided in the webhook header. If they match, you can be confident that:

• The webhook originated from the legitimate sender.
• The payload has not been tampered with during transit.

Best Practices for Implementation

To ensure maximum security, consider these best practices when implementing webhook signature verification:

• Use Strong Secrets: Generate long, random, alphanumeric strings for your shared secrets. Never hardcode them directly into your application; use environment variables or a secure secret management service.
• Rotate Secrets Regularly: Periodically rotate your shared secrets to mitigate the risk of compromise. Have a mechanism to support multiple active secrets during a rotation period.
• Timestamp Verification: Many webhook providers include a timestamp in the signature header. You should verify this timestamp to guard against replay attacks. If a webhook arrives with a timestamp that is too old (e.g., more than 5 minutes), reject it.
• Consistent Hashing Algorithm: Ensure your application uses the exact same cryptographic hash algorithm (e.g., HMAC-SHA256, HMAC-SHA512) and encoding as the webhook sender.
• Raw Payload: Always use the raw request body for hashing, not a parsed version. Any minor change, like whitespace or reordering of JSON keys, can invalidate the signature.
• Error Handling: Implement reliable error handling for failed signature verifications. Log these attempts and consider alerting your security team.
• HTTPS Only: Always receive webhooks over HTTPS to encrypt the communication channel and prevent eavesdropping.

Example: Verifying a Didit Webhook Signature

Let's illustrate how webhook signature verification might look in practice, using a hypothetical Node.js example for a Didit webhook.

First, you'd configure your webhook endpoint in the Didit dashboard and receive a secret key.

const crypto = require('crypto');
const express = require('express');
const bodyParser = require('body-parser');

const app = express();
const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET; // Store securely!

// Use raw body parser for webhooks to get the unparsed body
app.use(bodyParser.raw({ type: 'application/json' }));

app.post('/didit-webhook', (req, res) => {
  const signatureHeader = req.headers['x-didit-signature'];
  const timestampHeader = req.headers['x-didit-timestamp']; // Optional, but good practice
  const rawBody = req.body;

  if (!signatureHeader || !DIDIT_WEBHOOK_SECRET) {
    return res.status(400).send('Missing signature header or webhook secret.');
  }

  // Reconstruct the signed payload: timestamp + '.' + rawBody
  // (assuming Didit uses this format, check documentation)
  const signedPayload = `${timestampHeader}.${rawBody.toString('utf8')}`;

  const expectedSignature = crypto
    .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');

  if (crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expectedSignature))) {
    // Signature is valid, now process the webhook payload
    try {
      const event = JSON.parse(rawBody.toString('utf8'));
      console.log('Received verified webhook event:', event.type);
      // Handle your event logic here (e.g., update user status, trigger fraud review)
      res.status(200).send('Webhook received and verified.');
    } catch (parseError) {
      console.error('Error parsing webhook body:', parseError);
      res.status(400).send('Invalid JSON payload.');
    }
  } else {
    console.warn('Webhook signature verification failed for:', signatureHeader);
    res.status(403).send('Invalid webhook signature.');
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

Note: The exact format of the signed payload (e.g., timestamp + '.' + rawBody) and the header names (x-didit-signature, x-didit-timestamp) will be specified in the documentation of your webhook provider. Always refer to the official documentation for the precise implementation details. Didit's webhooks follow common industry standards, ensuring straightforward integration.

Key Takeaways

• Webhook signature verification is essential for the security and integrity of real-time identity and fraud data.
• It protects against data tampering, replay attacks, and unauthorized access.
• The process involves a shared secret, cryptographic hashing, and signature comparison.
• Best practices include strong secrets, regular rotation, timestamp verification, and using raw payloads for hashing.
• Always implement webhook signature verification for any system dealing with sensitive information, especially in identity and fraud prevention.

Frequently asked questions

What is webhook signature verification?

Webhook signature verification is a security mechanism that uses a shared secret and cryptographic hashing to confirm that a webhook payload was sent by a legitimate source and has not been altered in transit.

Why is webhook signature verification important for identity workflows?

For identity workflows, webhook signature verification prevents fraudsters from spoofing identity verification results, tampering with fraud alerts, or injecting malicious data, thereby protecting the integrity of your user onboarding and transaction monitoring processes.

What happens if I don't implement webhook signature verification?

Without webhook signature verification, your application is vulnerable to various attacks, including data manipulation, unauthorized access to your systems, and potentially severe financial and reputational damage due to fraud or compliance breaches.

Can HTTPS alone secure my webhooks?

While HTTPS encrypts the communication channel, protecting against eavesdropping, it does not prevent a malicious actor from creating their own webhook requests and sending them to your endpoint. Webhook signature verification is necessary to authenticate the sender and verify data integrity.

What is a replay attack?

A replay attack occurs when a malicious actor intercepts a legitimate webhook and resends it at a later time to trick your system into processing the same event multiple times or performing an action based on outdated information. Timestamp verification, alongside signature verification, helps mitigate this risk.

Didit provides comprehensive infrastructure for identity and fraud, including reliable webhook notifications for all identity verification (User Verification / KYC, Business Verification / KYB) and fraud detection (Transaction Monitoring, Wallet Screening / KYT) modules. Our platform ensures that all webhook events are signed, enabling you to implement webhook signature verification easily and secure your real-time data flows. Integrate Didit in minutes and start with 500 free checks every month, with full identity verifications from $0.30, backed by industry-standard security measures like webhook signature verification.

Get started with Didit

Didit is infrastructure for identity and fraud — one API, public pay-per-use pricing, and 500 free verifications every month. Add User Verification to your flow and integrate in 5 minutes.

• User Verification — see how it works and what it costs.
• Read the documentation — API reference and integration guide.
• Start free — 500 verifications every month, no credit card required.