Webhook Integration Guide

Download this guide

The SNH AI Background Check API provides comprehensive webhook support to receive real-time notifications throughout the verification lifecycle. This guide covers practical webhook configuration, security implementation, payload handling, and complete integration examples. For a high-level overview of the webhook system and when events are triggered, see the Webhook System Overview.

Delivery model

Webhooks are signed and retried according to retryAttempts. These delivery mechanics — retries, signing, and backoff — are identical in sandbox and production; the delivery service has no environment-conditional logic for them. Any “best-effort” feel to sandbox testing is a function of how you configure your own test organization and webhook receiver, not a platform guarantee that differs by environment. See Environments.

Overview

Webhooks are HTTP callbacks that notify your application when verification events occur. The API sends POST requests to your configured endpoints with event payloads and HMAC-SHA256 signatures for security verification.

Illustrative terminal payloads (`verification.completed`)

Structures vary by organization program; illustrative fragments only: Employment (verified)

{
  "event": "verification.completed",
  "data": {
    "searchType": "EMPLOYMENT",
    "verificationResult": {
      "outcome": "VERIFIED",
      "employmentDates": {
        "startDate": "2020-01-15",
        "endDate": "2023-06-30"
      },
      "positionTitle": "Software Engineer",
      "salaryBand": { "currency": "USD", "max": 150000 }
    }
  }
}

Education (verified)

{
  "event": "verification.completed",
  "data": {
    "searchType": "EDUCATION",
    "verificationResult": {
      "outcome": "VERIFIED",
      "degree": "BS Computer Science",
      "completionDate": "2018-05-15",
      "gpa": "3.7"
    }
  }
}

Action required (third-party / manual)

{
  "event": "verification.action_required",
  "data": {
    "reasonCode": "THIRD_PARTY_RECORD",
    "searchType": "EMPLOYMENT",
    "metadata": { "routingHint": "contact_verifier_via_portal" }
  }
}

Complete field lists: Webhook events.

Webhook Events

The API sends three types of webhook events:

verification.completed - Sent when a verification search reaches a terminal outcome (VERIFIED, NO_RECORD, WRONG_ORG, THIRD_PARTY, etc., per your program)
verification.action_required - Sent when the verification cannot proceed without action (THIRD_PARTY_RECORD, UPSTREAM_ISSUE, SYSTEM_FAILURE, SLA_REACHED, HUMAN_ESCALATION, OTHER)
verification.notification - Intermediate progress updates (contact plan, outbound attempts, inbound messages) when those notifications are enabled for your routing

For complete details on event types, payload structures, and when events are triggered, see Webhook Events.

Webhook Configuration

Webhooks can be configured at two levels:

Request-Level Configuration

Configure webhooks per verification request:

{
  "applicant": {
    /* ... */
  },
  "searchTypes": [
    /* ... */
  ],
  "webhookConfig": {
    "enabled": true,
    "secret": "your-webhook-secret-key",
    "retryAttempts": 3,
    "closeoutEndpoints": {
      "EMPLOYMENT": [
        {
          "url": "https://your-app.com/webhooks/employment",
          "headers": { "X-Customer": "acme" },
          "events": ["verification.completed"]
        },
        {
          "url": "https://your-app.com/webhooks/employment-notify",
          "events": ["verification.notification"]
        }
      ],
      "EDUCATION": [
        {
          "url": "https://your-app.com/webhooks/education",
          "basicAuth": { "username": "api", "password": "secret" },
          "events": ["verification.completed"]
        }
      ]
    },
    "fallbackEndpoint": [
      {
        "url": "https://your-app.com/webhooks/default",
        "events": ["verification.action_required"],
        "searchTypes": ["EMPLOYMENT", "EDUCATION"]
      }
    ]
  }
}

Organization-level Configuration

Configure webhooks at the organization level (applies to all verifications unless overridden): Contact your SNH AI account manager to configure organization-level webhook settings.

Endpoint Resolution

Webhook configuration comes from two sources: your organization-level settings (stored against your account) and the request-level webhookConfig on a given order. These are not an all-or-nothing override — they are merged field by field:

enabled, secret, retryAttempts: the request-level value is used if present, otherwise the organization-level value applies.
closeoutEndpoints: merged per search type key. If the request supplies targets for EMPLOYMENT but not EDUCATION, the request’s EMPLOYMENT targets fully replace the organization’s EMPLOYMENT targets, while the organization’s EDUCATION targets still apply — even though the request did supply a closeoutEndpoints object overall. Providing config for one search type never suppresses the organization’s config for a different, unmentioned search type.
fallbackEndpoint: replaced wholesale, not merged per-field. If the request supplies a fallbackEndpoint, it fully replaces the organization’s fallback; otherwise the organization’s fallback is used.

Once the config is merged, the API resolves delivery targets per event and search type, independently:

Type-specific targets: targets configured under closeoutEndpoints[searchType] that allow the event (events array) are included.
Fallback targets: targets under fallbackEndpoint that allow the event and, if the target sets searchTypes, include the resolved search type, are also included.

Type-specific and fallback targets are not mutually exclusive tiers — a fallback target can still receive an event alongside a type-specific target for the same search type if both match the event’s filters. The API delivers to every matching target concurrently. Notes:

If events is omitted on a target, it will receive only verification.completed (backward compatible).
Per-target headers are merged into the request headers. If basicAuth is set, an Authorization: Basic ... header is included.

Webhook Payload Structure

All webhook payloads follow a consistent structure with event, occurredAt, and data fields. For detailed payload structures and examples, see Webhook Events. Terminal events (verification.completed, verification.action_required) always include a single channel field representing the primary verification channel. Intermediate notifications keep the original channels array to provide full auditing of concurrent communication paths.

Webhook Headers

Each webhook request includes these headers:

Header	Description
`Content-Type`	Always `application/json`.
`X-Event-Type`	Event type (`verification.completed`, `verification.action_required`, `verification.notification`).
`X-Event-Id`	Unique delivery ID for this webhook (use for idempotency).
`X-Search-Type`	Optional; resolved search type: `EMPLOYMENT` or `EDUCATION`.
`X-External-Search-Id`	Optional; echoes the external search identifier provided when the order was created.
`X-Endpoint-Source`	Indicates whether the request used a `type-specific` or `fallback` endpoint.
`User-Agent`	Always `Theary-Webhook-Delivery/1.0`.¹
`Authorization`	Present only when the webhook target specifies Basic Auth credentials (`Authorization: Basic <base64(username:password)>`).
`X-Webhook-Signature`	Included when an organization-level or per-target secret is configured; value is `sha256=<hex>` for HMAC validation.

Notes:

If neither the organization config nor the target defines a signing secret, X-Webhook-Signature is omitted.
Per-target custom headers are merged into the request when configured (for example X-Customer: acme).

Security: Signature Verification

All webhook payloads are signed using HMAC-SHA256. Verify the signature to ensure authenticity:

Node.js Example

const crypto = require('crypto')

function verifyWebhookSignature(rawBody, signature, secret) {
  // Extract signature from "sha256=<hex>" format
  const signatureValue = signature.replace('sha256=', '')

  const expectedSignature = crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex')

  return crypto.timingSafeEqual(Buffer.from(signatureValue, 'hex'), Buffer.from(expectedSignature, 'hex'))
}

// In your webhook handler
app.post('/webhooks/verification', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature']
  const secret = process.env.WEBHOOK_SECRET

  // Verify signature using raw body
  if (!verifyWebhookSignature(req.body.toString(), signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' })
  }

  // Parse JSON after verification
  const payload = JSON.parse(req.body.toString())

  // Process webhook
  res.status(200).json({ received: true })
})

Bash / OpenSSL (compare hex digest)

Matches the server’s sha256= hex computation when given the exact raw UTF-8 POST body ($BODY) and $WEBHOOK_SECRET:

BODY='{"event":"verification.completed","occurredAt":"2026-01-01T00:00:00.000Z","data":{}}'
WEBHOOK_SECRET='your-webhook-secret-key'

HEX="$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $NF}')"
echo "Compare X-Webhook-Signature to: sha256=$HEX"

Python Example

import hmac
import hashlib
import json
from flask import request

def verify_webhook_signature(raw_body: bytes, signature: str, secret: str) -> bool:
    # Extract signature from "sha256=<hex>" format
    signature_value = signature.replace('sha256=', '')

    expected_signature = hmac.new(
        secret.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature_value, expected_signature)

# In your webhook handler
@app.route('/webhooks/verification', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    secret = os.environ.get('WEBHOOK_SECRET')

    # Verify using raw request bytes to match server-side HMAC calculation
    raw_body = request.get_data()
    if not verify_webhook_signature(raw_body, signature, secret):
        return jsonify({'error': 'Invalid signature'}), 401

    # Process webhook
    return jsonify({'received': True}), 200

For detailed event payload structures and examples, see Webhook Events.

Common webhook mistakes

Skipping signature verification — never trust unsigned or unvalidated payloads when a secret applies.
Assuming synchronous completion — polls return before terminal outcomes; verification.completed is async.
Ignoring idempotency — X-Event-Id can repeat across retries (retryAttempts); dedupe deliveries.
Missing event handlers — implement verification.completed, verification.action_required, verification.notification as needed for your UX.

Integration Examples

Express.js Webhook Handler

const express = require('express')
const crypto = require('crypto')
const app = express()

// Middleware to capture raw body for signature verification
app.use('/webhooks/verification', express.raw({ type: 'application/json' }))

function verifySignature(rawBody, signature, secret) {
  // Extract signature from "sha256=<hex>" format
  const signatureValue = signature.replace('sha256=', '')

  const expectedSignature = crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex')

  return crypto.timingSafeEqual(Buffer.from(signatureValue, 'hex'), Buffer.from(expectedSignature, 'hex'))
}

app.post('/webhooks/verification', (req, res) => {
  const signature = req.headers['x-webhook-signature']
  const secret = process.env.WEBHOOK_SECRET

  // Verify signature using raw body
  if (!verifySignature(req.body.toString(), signature, secret)) {
    console.error('Invalid webhook signature')
    return res.status(401).json({ error: 'Invalid signature' })
  }

  // Parse JSON after verification
  const payload = JSON.parse(req.body.toString())
  const { event, occurredAt, data } = payload

  // Handle different event types
  switch (event) {
    case 'verification.completed':
      handleVerificationCompleted(data)
      break
    case 'verification.action_required':
      handleVerificationActionRequired(data)
      break
    case 'verification.notification':
      handleVerificationNotification(data)
      break
    default:
      console.warn('Unknown event type:', event)
  }

  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true })
})

function handleVerificationCompleted(data) {
  const { searchId, verificationId, searchType, verificationResult } = data

  console.log(`Verification completed: ${searchId}`)
  console.log(`Outcome: ${verificationResult.outcome}`)
  console.log(`Search Type: ${searchType}`)

  // Update your database
  // Send notifications to your users
  // Trigger downstream processes
}

function handleVerificationActionRequired(data) {
  const { searchId, reasonCode, contact, metadata } = data

  console.warn(`Verification action required: ${searchId}`)
  console.warn(`Reason Code: ${reasonCode}`)
  if (contact) console.warn(`Contact: ${JSON.stringify(contact)}`)
  if (metadata) console.warn(`Metadata: ${JSON.stringify(metadata)}`)

  // Alert your team or end-user
  // Guide user to next steps (e.g., submit via third-party portal)
}

function handleVerificationNotification(data) {
  const { searchId, messageId, classification } = data

  console.log(`Notification received: ${searchId}`)
  console.log(`Classification: ${classification.type}`)

  // Update UI in real-time
  // Log notification for audit
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000')
})

Flask Webhook Handler (Python)

from flask import Flask, request, jsonify
import hmac
import hashlib
import os

app = Flask(__name__)

def verify_signature(raw_body, signature, secret):
    # Extract signature from "sha256=<hex>" format
    signature_value = signature.replace('sha256=', '')

    expected_signature = hmac.new(
        secret.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature_value, expected_signature)

@app.route('/webhooks/verification', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    secret = os.environ.get('WEBHOOK_SECRET')

    # Get raw body for signature verification
    raw_body = request.get_data()

    # Verify signature using raw body
    if not verify_signature(raw_body, signature, secret):
        return jsonify({'error': 'Invalid signature'}), 401

    # Parse JSON after verification
    payload = request.json
    event = payload.get('event')
    data = payload.get('data')

    # Handle different event types
    if event == 'verification.completed':
        handle_verification_completed(data)
    elif event == 'verification.action_required':
        handle_verification_action_required(data)
    elif event == 'verification.notification':
        handle_verification_notification(data)
    else:
        print(f'Unknown event type: {event}')

    return jsonify({'received': True}), 200

def handle_verification_completed(data):
    search_id = data.get('searchId')
    verification_result = data.get('verificationResult')

    print(f'Verification completed: {search_id}')
    print(f'Outcome: {verification_result.get("outcome")}')

    # Update your database
    # Send notifications
    # Trigger downstream processes

def handle_verification_action_required(data):
    search_id = data.get('searchId')
    reason_code = data.get('reasonCode')
    contact = data.get('contact')
    metadata = data.get('metadata')

    print(f'Action required: {search_id}')
    print(f'Reason: {reason_code}')
    if contact:
        print(f'Contact: {contact}')
    if metadata:
        print(f'Metadata: {metadata}')

def handle_verification_notification(data):
    search_id = data.get('searchId')
    classification = data.get('classification', {})

    print(f'Notification received: {search_id}')
    print(f'Classification: {classification.get("type")}')

    # Update UI in real-time

if __name__ == '__main__':
    app.run(port=3000)

Retry Logic

The API automatically retries failed webhook deliveries, identically in sandbox and production:

Retry attempts: Configurable (default: 3, max: 10)
Backoff strategy: Exponential backoff with jitter
Retry timing: 2^attempt seconds (e.g., 2s, 4s, 8s)
Client errors (4xx): Not retried
Server errors (5xx): Retried with exponential backoff

Rely on this retry behavior for both environments when validating handlers and building alerting.

Best Practices

1. Always Verify Signatures

Never process webhooks without verifying the HMAC signature. This ensures the webhook is from SNH AI and hasn’t been tampered with.

2. Respond Quickly

Respond with HTTP 200 status code as soon as you receive the webhook. Perform heavy processing asynchronously.

3. Handle Idempotency

Webhooks may be retried, so ensure your handlers are idempotent. Use the X-Event-Id header to track processed events.

4. Use HTTPS Endpoints

Always use HTTPS endpoints for webhook delivery in production. Non-production environments may also accept http://localhost and http://127.0.0.1 for local testing.

5. Monitor Webhook Delivery

Track delivery status and set up alerts for failed deliveries. Monitor your logs for webhook processing errors.

6. Store Secrets Securely

Never hardcode webhook secrets. Use environment variables or secure secret management services.

7. Test with Webhook Testing Tools

Use tools like ngrok or webhook.site to test your webhook endpoints during development.

Error Handling

HTTP Status Codes

Your webhook endpoint should return appropriate HTTP status codes:

200 OK: Webhook received and processed successfully
400 Bad Request: Invalid payload format (not retried)
401 Unauthorized: Invalid signature (not retried)
500 Internal Server Error: Server error (will be retried)

Handling Failures

If your endpoint fails to process a webhook:

The API retries based on your retryAttempts configuration
After all retries are exhausted, delivery stops for that attempt
Make your handler idempotent with X-Event-Id, and consider a dead-letter queue for events you could not process
Prefer polling Get specific search when you need to reconcile search state — webhook delivery history is not exposed as a separate order-events API

Testing Webhooks

Using ngrok

# Install ngrok
npm install -g ngrok

# Start your local server
node server.js

# Expose it via ngrok
ngrok http 3000

# Use the ngrok URL in your webhook config
# https://abc123.ngrok.io/webhooks/verification

Using webhook.site

Visit webhook.site
Copy the unique URL provided
Use it in your webhook configuration for testing
View incoming webhooks in real-time

Troubleshooting

Webhooks Not Received

Check endpoint URL: Ensure your endpoint is accessible via HTTPS
Verify signature: Check that your secret matches the one in the webhook config
Check firewall: Ensure your server allows incoming connections from SNH AI
Review logs: Check API logs for webhook delivery errors

Invalid Signature Errors

Verify secret: Ensure the secret in your code matches the one in webhook config
Check payload format: Ensure you’re serializing the payload correctly
Encoding: Verify HMAC-SHA256 is using the correct encoding (hex)

Webhooks Received Multiple Times

Idempotency: Implement idempotency checks using X-Event-Id
Retry logic: This is expected behavior - the API retries failed deliveries
Duplicate detection: Store processed event IDs to prevent duplicate processing

Webhook config Schema - Webhook configuration schema
Create Order - Creating orders with webhook configuration
Error Handling - Error handling best practices

“Theary” is the product/platform name reflected in this wire-level identifier. It refers to the same product as “SNH AI,” the company name used elsewhere in these docs. ↩

​Webhook Integration Guide

​Delivery model

​Overview

​Illustrative terminal payloads (verification.completed)

​Webhook Events

​Webhook Configuration

​Request-Level Configuration

​Organization-level Configuration

​Endpoint Resolution

​Webhook Payload Structure

​Webhook Headers

​Security: Signature Verification

​Node.js Example

​Bash / OpenSSL (compare hex digest)

​Python Example

​Common webhook mistakes

​Integration Examples

​Express.js Webhook Handler

​Flask Webhook Handler (Python)

​Retry Logic

​Best Practices

​1. Always Verify Signatures

​2. Respond Quickly

​3. Handle Idempotency

​4. Use HTTPS Endpoints

​5. Monitor Webhook Delivery

​6. Store Secrets Securely

​7. Test with Webhook Testing Tools

​Error Handling

​HTTP Status Codes

​Handling Failures

​Testing Webhooks

​Using ngrok

​Using webhook.site

​Troubleshooting

​Webhooks Not Received

​Invalid Signature Errors

​Webhooks Received Multiple Times

​Related Documentation

Footnotes