Webhook Integration Guide

Step-by-step guide to integrating VerifyHQ webhooks into your application.

1. Set Up Your Endpoint

Create an HTTPS endpoint on your server that accepts POST requests. The endpoint must be publicly accessible.

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/verifyhq', (req, res) => {
  const { event, data, timestamp } = req.body;
  
  switch (event) {
    case 'identity.verified':
      console.log(`User ${data.userId} verified!`);
      // Update user status in your database
      break;
    case 'document.rejected':
      console.log(`Document ${data.verificationId} rejected`);
      // Notify user to resubmit
      break;
    case 'liveness.failed':
      console.log(`Liveness failed for ${data.userId}`);
      break;
  }
  
  res.status(200).send('OK');
});

2. Register Your Webhook

Use the webhooks API to register your endpoint and select which events to receive.

3. Verify Signatures

Always verify the X-Webhook-Signature header to ensure the request came from VerifyHQ. See the Webhooks API reference for implementation details.

4. Retry Policy

Failed deliveries (non-2xx response or timeout) are retried up to 3 times with exponential backoff:

• 1st retry: 1 minute after failure
• 2nd retry: 5 minutes after 1st retry
• 3rd retry: 30 minutes after 2nd retry

Best Practices

• Respond with 200 quickly — process events asynchronously
• Store the raw payload before processing
• Use a message queue for reliable processing
• Monitor delivery failures in the dashboard
• Test with sandbox webhooks before going live