Webhook System Overview

Download this guide

The SNH AI webhook system provides real-time notifications throughout the verification lifecycle. This guide explains how webhooks fit into the overall verification workflow and when different webhook events are triggered.

Verification Lifecycle

The verification workflow consists of several phases, each triggering specific webhook events:

Webhook Event Types

SNH AI sends three types of webhook events:

1. verification.completed

When it’s sent:

Verification reaches a terminal outcome (VERIFIED, NO_RECORD, WRONG_ORG, THIRD_PARTY)
All verification data has been processed and validated
Results are ready for consumption by your system

What it contains:

Complete verification result with all extracted data
Full employment or education verification object (provided vs verified fields)
Discrepancy flag indicating if verified data differs from provided data
Research decision log (audit trail of contact discovery)
Education accreditation data (for EDUCATION searches)
Terminal channel used (EMAIL, VOICE, or FAX)

Use this to:

Update your applicant records with verified data
Mark verifications as complete in your system
Trigger downstream workflows (e.g., send results to hiring manager)
Generate reports or analytics

2. verification.action_required

When it’s sent:

Verification cannot proceed without manual intervention
Third-party vendor is required (THIRD_PARTY_RECORD)
International education third-party detection (INTERNATIONAL_EDUCATION)
External service failure (UPSTREAM_ISSUE)
Internal system error (SYSTEM_FAILURE)
SLA timeout exceeded (SLA_REACHED)
All automation exhausted (HUMAN_ESCALATION)

What it contains:

Reason code explaining why action is required
Structured contact payload for employment or education searches
Metadata with troubleshooting context
Research decision log (for HUMAN_ESCALATION)
Contact plan data (when escalating with research results)

Use this to:

Alert your team or end-user about the issue
Route to appropriate handler based on reason code
Guide users to next steps (e.g., submit via third-party portal)
Track verifications requiring intervention

3. verification.notification

When it’s sent:

Intermediate stages during the verification process
Research completes and generates a contact plan
Outbound attempt is made (email sent, call initiated, fax dispatched)
Inbound response received (email reply, voicemail, fax received, or JSON submission)

What it contains:

Notification type (CONTACT_PLAN, OUTBOUND_ATTEMPT, INBOUND_MESSAGE, INBOUND_RECEIVED_DETAIL)
Contact plan with discovered contacts and confidence scores
Outbound attempt metadata (channel, destination, attempt number)
Inbound message classification and summary

Use this to:

Update UI in real-time with verification progress
Show contact attempts to end users
Track verification velocity and bottlenecks
Log activity for compliance and audit purposes

Webhook Configuration

Webhooks can be configured at two levels:

Organization-level Configuration

Global webhook settings for your organization, stored in your organization configuration. Contact your SNH AI account manager to configure organization-level webhooks. Benefits:

Applies to all verifications automatically
Centralized management
No per-request configuration needed

Request-Level Configuration

Per-verification webhook settings via the webhookConfig object in the order creation request. Benefits:

Override organization defaults for specific orders
Route different verification types to different endpoints
Apply custom headers or authentication per order

Example: Each value under closeoutEndpoints can be a string URL (legacy), one WebhookTarget object, or an array of URLs/objects. fallbackEndpoint accepts the same shapes.

{
  "webhookConfig": {
    "enabled": true,
    "secret": "your-webhook-secret",
    "retryAttempts": 3,
    "closeoutEndpoints": {
      "EMPLOYMENT": [
        {
          "url": "https://your-app.com/webhooks/employment",
          "events": ["verification.completed"]
        }
      ],
      "EDUCATION": [
        {
          "url": "https://your-app.com/webhooks/education",
          "events": ["verification.completed", "verification.notification"]
        }
      ]
    },
    "fallbackEndpoint": [
      {
        "url": "https://your-app.com/webhooks/all-events",
        "events": ["verification.action_required"],
        "searchTypes": ["EMPLOYMENT", "EDUCATION"]
      }
    ]
  }
}

Webhook Routing

Organization-level and request-level webhook config are merged field by field — providing a request-level target for one search type doesn’t suppress the organization’s config for a different search type, and type-specific and fallback targets aren’t exclusive tiers (both can receive an event concurrently if they match its filters). For the full merge and resolution behavior, see the canonical guide: Webhook Integration — Endpoint Resolution.

Security, retries, and delivery

Webhooks are signed with HMAC-SHA256 (X-Webhook-Signature), identified for idempotency with X-Event-Id, and retried on transient failures. For signature verification code, header tables, retry/backoff rules, and handler best practices, see the canonical guide: Webhook Integration.

Research Decision Log

For verifications that complete research (contact discovery), webhooks include a researchDecisionLog object that provides full transparency into how contacts were found:

{
  "researchDecisionLog": {
    "timestamp": "2025-12-09T10:30:00Z",
    "organizationName": "Acme Corporation",
    "location": "San Francisco, CA",
    "decisions": [
      {
        "stage": "ORG_PREFERENCE_SEARCH",
        "decision": "PROCEED",
        "reasoning": "Found 2 contacts from organization preference table",
        "confidence": 0.95,
        "timestamp": "2025-12-09T10:30:01Z"
      },
      {
        "stage": "WEB_SEARCH",
        "decision": "SKIP",
        "reasoning": "Sufficient contacts from org preferences; web search not needed",
        "timestamp": "2025-12-09T10:30:02Z"
      }
    ]
  }
}

Each decision records one of seven research stages (organization preferences, verified contacts, internal search, parent organization search, web search, channel policy check, or final result). For the full stage-by-stage table, see Webhook Events — Research Stages.

Education Accreditation

For EDUCATION searches, completed and action_required webhooks include accreditation data:

{
  "accreditation": {
    "reference": {
      "name": "Stanford University",
      "date": "2022-06-12",
      "city": "Stanford",
      "state": "CA"
    },
    "matches": [
      {
        "campus": {
          "dapipId": "243744",
          "locationName": "Stanford University",
          "city": "Stanford",
          "state": "CA",
          "url": "https://www.stanford.edu"
        },
        "accreditation": {
          "statusLabel": "Accredited",
          "isAccredited": true,
          "accreditor": "WASC Senior College and University Commission",
          "validFrom": "1949-01-01",
          "validThrough": null,
          "reason": "Accredited from 1949-01-01 through present"
        }
      }
    ],
    "metadata": {
      "accreditationStatus": "accredited",
      "campusesConsidered": 1,
      "dataSource": "DAPIP Database",
      "checkedOn": "2025-12-02"
    }
  }
}

The system automatically:

Looks up institutions in the DAPIP (Database of Accredited Postsecondary Institutions) database
Checks accreditation status at the reference date (graduation or attendance)
Provides campus details, accreditor information, and historical timeline
Suggests alternate campuses when exact match is not found

Next Steps

Webhook Integration — signatures, retries, handlers, and testing
Webhook Events — payload structures and field reference
Error handling — API and delivery failure guidance

​Webhook System Overview

​Verification Lifecycle

​Webhook Event Types

​1. verification.completed

​2. verification.action_required

​3. verification.notification

​Webhook Configuration

​Organization-level Configuration

​Request-Level Configuration

​Webhook Routing

​Security, retries, and delivery

​Research Decision Log

​Education Accreditation

​Next Steps

Webhook System Overview

Verification Lifecycle

Webhook Event Types

1. verification.completed

2. verification.action_required

3. verification.notification

Webhook Configuration

Organization-level Configuration

Request-Level Configuration

Webhook Routing

Security, retries, and delivery

Research Decision Log

Education Accreditation

Next Steps