> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.theary.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook System Overview

> Understanding how SNH AI webhook notifications work in the verification workflow

# Webhook System Overview

<p>
  <a href="/assets/downloads/guides/overview.pdf" download="overview.pdf">Download this guide</a>
</p>

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:

```mermaid theme={null}
graph TD
    A[Order Created] --> B[Research Phase]
    B --> C[Contact Discovery]
    C --> D{Contacts Found?}
    D -->|Yes| E[Contact Plan Generated]
    D -->|No| F[Human Escalation]
    E --> G[Outbound Attempts]
    G --> H{Response Received?}
    H -->|Yes| I[Document Processing]
    H -->|No| J{Retry/Escalate}
    I --> K{Result Valid?}
    K -->|Yes| L[Verification Complete]
    K -->|No| M[Action Required]
    J --> F
    F --> N[Manual Intervention]

    E -.->|verification.notification| E1[Contact Plan Webhook]
    G -.->|verification.notification| G1[Outbound Attempt Webhook]
    H -.->|verification.notification| H1[Inbound Message Webhook]
    L -.->|verification.completed| L1[Completed Webhook]
    M -.->|verification.action_required| M1[Action Required Webhook]
    F -.->|verification.action_required| F1[Escalation Webhook]
```

## 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](/api-reference/schemas/webhook-target) object, or an **array** of URLs/objects. `fallbackEndpoint` accepts the same shapes.

```json theme={null}
{
  "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](/webhooks/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](/webhooks/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:

```json theme={null}
{
  "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](/webhooks/events#research-stages).

## Education Accreditation

For EDUCATION searches, completed and action\_required webhooks include accreditation data:

```json theme={null}
{
  "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](/webhooks/integration) — signatures, retries, handlers, and testing
* [Webhook Events](/webhooks/events) — payload structures and field reference
* [Error handling](/guides/error-handling) — API and delivery failure guidance