Webhook System Overview

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
Education accreditation data (for EDUCATION searches)
Terminal channel used (EMAIL, VOICE, or FAX)
Verification question answers (data.verificationQuestions and data.questionnaire) for EMPLOYMENT/EDUCATION — standard questions always; custom questions when defined at order creation

Use this to:

Update your applicant records with verified data
Persist custom and standard question answers (index by fieldKey / questionId; treat multi_select as arrays)
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)
External service failure (UPSTREAM_ISSUE)
Internal system error (SYSTEM_FAILURE)
SLA timeout exceeded (SLA_REACHED)
All automation exhausted (HUMAN_ESCALATION), including questionnaire gates:
- Missing required custom answers (MISSING_REQUIRED_INFORMATION)
- Invalid form marks (VERIFICATION_DATA_INVALID)
- Voice-only contact with no email or fax (VOICE_ONLY_NOT_SUPPORTED)

What it contains:

Reason code explaining why action is required
Structured contact payload for employment or education searches
Metadata with troubleshooting context (for questionnaire gates: escalationSubtype, partial verificationQuestions, missingQuestionIds / invalidFields)
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 and metadata.escalationSubtype
Surface incomplete or invalid custom-question forms for ops review
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
Contact plan is changed through the public contact APIs
Outbound attempt is made (email sent, call initiated, fax dispatched)
Pending outbound is paused or resumed through the public API
Inbound response received (email reply, voicemail, fax received, or JSON submission)

What it contains:

Notification type (CONTACT_PLAN, contact mutation types, OUTBOUND_ATTEMPT, outbound pause/resume types, INBOUND_MESSAGE, INBOUND_RECEIVED_DETAIL, or SEARCH_UPDATED)
Contact plan with discovered contacts and confidence scores
Outbound attempt metadata (channel, destination, attempt number)
Outbound pause/resume metadata (affected outbound, count, reason)
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.

Education Accreditation

For EDUCATION searches, completed and action_required webhooks include accreditation data indicating whether the institution is accredited:

{
  "accreditation": {
    "isAccredited": true,
    "statusLabel": "Accredited",
    "accreditor": "WASC Senior College and University Commission",
    "checkedOn": "2025-12-02"
  }
}

The system automatically checks accreditation status for the institution at the time of verification and returns a summary outcome.

Custom verification questions

Define custom questions on each search at order creation (searchTypes[].verificationQuestions). Answers return on verification.completed; incomplete or invalid required answers escalate on verification.action_required instead.

Concern	Where to look
Authoring questions, types, conditions, channel selection	Verification question
Completed payload fields and examples	Webhook events — verification questions
Escalation subtypes and examples	Webhook events — questionnaire metadata
Signatures, retries, handler patterns	Webhook integration

Next Steps

Webhook Integration — signatures, retries, handlers, and testing
Webhook Events — payload structures and field reference
Verification question — custom questions end-to-end
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

​Education Accreditation

​Custom verification questions

​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

Education Accreditation

Custom verification questions

Next Steps