Handling Verification Webhooks

Overview

Webhooks allow you to receive real-time notifications when verification events occur. This is more efficient than polling the API.

Step 1: Create a Webhook Endpoint

First, create an endpoint in your application to receive webhook events.

// Express.js example
app.post('/webhooks/credlyr', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-credlyr-signature'];
  const payload = req.body;

  // Verify signature (see next step)
  // Process event

  res.status(200).send('OK');
});

Step 2: Verify Webhook Signatures

Always verify webhook signatures to ensure requests are from CredLyr.

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

Step 3: Handle Events

Process different event types based on your application needs.

const event = JSON.parse(payload);

switch (event.type) {
  case 'verification.completed':
    const verification = event.data;
    if (verification.status === 'approved') {
      await handleApprovedVerification(verification);
    } else if (verification.status === 'denied') {
      await handleDeniedVerification(verification);
    }
    break;
  case 'verification.expired':
    await handleExpiredVerification(event.data);
    break;
}