Webhooks

Webhooks allow you to receive real-time updates about verification events in your application. When a verification status changes, Vericato will send an HTTP POST request to your configured webhook URL.

Webhooks are only available for Premium plan customers.

Configuring Webhooks

Go to your Vericato dashboard
Navigate to Settings > Webhooks
Enable webhooks and enter your webhook URL
Make sure your endpoint can receive POST requests over HTTPS
Save your webhook configuration

Webhook Events

Vericato sends webhook notifications for the following events:

Verification Verified Event

Triggered when a verification is successfully completed.

{
  "event": "verification.verified",
  "timestamp": "2025-11-14T10:30:00.000Z",
  "data": {
    "verification_id": "ver_123abc",
    "verification_status": "verified",
    "verification_original_name": "John Doe",
    "verification_verified_name": "John William Doe",
    "verification_date_identified": "2025-11-14T10:25:00.000Z",
    "verification_method": "passport",
    "company_id": "comp_456def",
    "company_name": "Your Company Name",
    "original_verification": {
      "created_at": "2025-11-14T09:00:00.000Z",
      "updated_at": "2025-11-14T10:25:00.000Z",
      "expires_at": "2025-11-21T09:00:00.000Z",
      "email": "[email protected]",
      "purpose": "identity_verification"
    }
  }
}

Verification Failed Event

Triggered when a verification fails.

{
  "event": "verification.failed",
  "timestamp": "2025-11-14T10:30:00.000Z",
  "data": {
    "verification_id": "ver_123abc",
    "verification_status": "failed",
    "verification_original_name": "John Doe",
    "verification_failed_reason": "Document verification failed",
    "verification_method": "passport",
    "company_id": "comp_456def",
    "company_name": "Your Company Name",
    "original_verification": {
      "created_at": "2025-11-14T09:00:00.000Z",
      "updated_at": "2025-11-14T10:25:00.000Z",
      "expires_at": "2025-11-21T09:00:00.000Z",
      "email": "[email protected]",
      "purpose": "identity_verification"
    }
  }
}

Verification Expired Event

Triggered when a verification expires without successful completion.

{
  "event": "verification.expired",
  "timestamp": "2025-11-21T09:00:00.000Z",
  "data": {
    "verification_id": "ver_123abc",
    "verification_status": "expired",
    "verification_original_name": "John Doe",
    "verification_expired_date": "2025-11-21T09:00:00.000Z",
    "company_id": "comp_456def",
    "company_name": "Your Company Name",
    "original_verification": {
      "created_at": "2025-11-14T09:00:00.000Z",
      "updated_at": "2025-11-14T09:00:00.000Z",
      "expires_at": "2025-11-21T09:00:00.000Z",
      "email": "[email protected]",
      "purpose": "identity_verification"
    }
  }
}

Webhook Headers

Each webhook request includes the following headers:

Header	Description
`Content-Type`	Always `application/json`
`User-Agent`	`Vericato-Webhook/1.0`
`X-Vericato-Event`	The event type (e.g., `verification.verified`)
`X-Vericato-Verification-Id`	The verification ID

Handling Webhooks

Here's an example of how to handle webhook events in your application:

Next.js App Router

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  try {
    const payload = await req.json();
    
    // Verify the event type
    const eventType = req.headers.get('X-Vericato-Event');
    
    switch (payload.event) {
      case "verification.verified":
        // Handle successful verification
        await handleVerificationSuccess(payload.data);
        break;
      
      case "verification.failed":
        // Handle failed verification
        await handleVerificationFailure(payload.data);
        break;
      
      case "verification.expired":
        // Handle expired verification
        await handleVerificationExpired(payload.data);
        break;
      
      default:
        console.log(`Unhandled event type: ${payload.event}`);
    }
    
    return NextResponse.json({ received: true }, { status: 200 });
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json(
      { error: "Webhook processing failed" },
      { status: 400 }
    );
  }
}

async function handleVerificationSuccess(data: any) {
  // Update your database with verified information
  console.log(`Verification ${data.verification_id} was successful`);
  // Your business logic here
}

async function handleVerificationFailure(data: any) {
  // Handle failed verification
  console.log(`Verification ${data.verification_id} failed: ${data.verification_failed_reason}`);
  // Your business logic here
}

async function handleVerificationExpired(data: any) {
  // Handle expired verification
  console.log(`Verification ${data.verification_id} expired`);
  // Your business logic here
}

Express.js

app.post('/webhooks/vericato', async (req, res) => {
  try {
    const payload = req.body;
    const eventType = req.headers['x-vericato-event'];
    
    switch (payload.event) {
      case 'verification.verified':
        await handleVerificationSuccess(payload.data);
        break;
      
      case 'verification.failed':
        await handleVerificationFailure(payload.data);
        break;
      
      case 'verification.expired':
        await handleVerificationExpired(payload.data);
        break;
    }
    
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(400).json({ error: 'Webhook processing failed' });
  }
});

Best Practices

Respond Quickly
- Return a 200 status code as soon as possible
- Process webhook data asynchronously if needed
- Webhook requests timeout after 10 seconds
Handle Retries
- Implement idempotency using the verification_id
- Store processed webhook IDs to prevent duplicate processing
- Vericato may resend webhooks if your endpoint doesn't respond with 200
Validate Requests
- Check the X-Vericato-Event header
- Verify the verification_id matches your records
- Only accept requests from your webhook URL path
Error Handling
- Log all webhook events for debugging
- Implement proper error handling
- Return appropriate HTTP status codes
Security
- Use HTTPS endpoints only
- Validate webhook payload structure
- Consider implementing IP allowlisting (contact support for Vericato's IP ranges)

Testing Webhooks

During development, you can use tools like:

ngrok or Cloudflare Tunnel to expose your local server
webhook.site or RequestBin to inspect webhook payloads
The webhook testing feature in your Vericato dashboard (coming soon)

Troubleshooting

Webhook Not Received

Verify your webhook URL is correct and accessible
Check that your endpoint accepts POST requests
Ensure your server returns a 200 status code
Verify you have a Premium plan subscription

Duplicate Webhooks

Webhooks may be retried if your endpoint doesn't respond with 200
Implement idempotency checking using verification_id
Store processed webhook IDs in your database

Timeout Errors

Webhook requests timeout after 10 seconds
Return 200 immediately and process data asynchronously
Move heavy processing to background jobs

Webhook Payload Reference

Common Fields

All webhook events include these fields:

Field	Type	Description
`event`	string	The event type (e.g., `verification.verified`)
`timestamp`	string	ISO 8601 timestamp when the webhook was sent
`data`	object	Event-specific data
`data.verification_id`	string	Unique identifier for the verification
`data.verification_status`	string	Current status: `verified`, `failed`, or `expired`
`data.verification_original_name`	string	Name provided when creating the verification
`data.company_id`	string	Your company ID
`data.company_name`	string	Your company name
`data.original_verification`	object	Original verification details

Event-Specific Fields

verification.verified

verification_verified_name - The verified name from the identity document
verification_date_identified - When the verification was completed
verification_method - Method used (e.g., passport, id_card, itsme, idin)

verification.failed

verification_failed_reason - Reason why the verification failed
verification_method - Method attempted (if applicable)

verification.expired

verification_expired_date - When the verification expired

Further Information

Create verification requests
Get verification details
Upgrade to Premium plan in your dashboard settings

Webhooks

On this page