Webhook Events Reference

Helium ID uses webhooks to notify your integration when verification progress changes or when a final outcome has been reached. All webhook payloads use the same outer JSON shape:

{
  "event": "verification.successful",
  "data": {}
}

The event field tells you what happened. The data field contains the event payload. If you want field-by-field payload definitions, see Webhook Payload Schemas.

Webhook destinations

Each API key can be configured with two webhook destinations:

Events webhook URL for progress updates
Decision webhook URL for final outcomes

Progress events help you keep your UI or internal workflow in sync. Decision events tell you that a verification has reached a terminal result.

Individual verification events

These events apply to sessions created with POST /v1/verifications.

Event	Destination	Terminal?	Meaning
`verification.started`	Events webhook	No	The end-user entered the hosted verification flow.
`verification.selfie_uploaded`	Events webhook	No	The end-user uploaded a selfie.
`verification.document_front_uploaded`	Events webhook	No	The end-user uploaded the front of their document.
`verification.document_back_uploaded`	Events webhook	No	The end-user uploaded the back of their document.
`verification.processing_started`	Events webhook	No	Helium ID started evaluating the submitted verification data.
`verification.biometrics_matched`	Events webhook	No	The selfie and document face check matched.
`verification.successful`	Decision webhook	Yes	The verification was approved.
`verification.failed`	Decision webhook	Yes	The verification was rejected.

Example individual decision payload

{
  "event": "verification.successful",
  "data": {
    "verificationId": "69d4f7657bcbe3b58b96b2f7",
    "vendorData": "user_12345",
    "statusCode": 2010,
    "docInfo": {
      "docType": "PASSPORT",
      "docNumber": "A1234567",
      "issueDate": "",
      "expiryDate": "2030-01-01",
      "issuingState": "GBR",
      "firstName": "JOHN",
      "lastName": "DOE",
      "middleName": "",
      "dob": "1990-01-01",
      "sex": "MALE"
    },
    "userSelfie": "https://example.com/selfie.jpg",
    "userIdBack": "",
    "userIdFront": "https://example.com/front.jpg"
  }
}

Company verification events

These events apply to sessions created with POST /v1/company-verifications.

Event	Destination	Terminal?	Meaning
`company_verification.submitted`	Events webhook	No	The representative completed the hosted flow and submitted the company verification.
`company_verification.liveness_completed`	Events webhook	No	The authorising-person liveness step completed.
`company_verification.under_review`	Events webhook	No	The company verification has moved into review.
`company_verification.successful`	Decision webhook	Yes	The company verification was approved.
`company_verification.failed`	Decision webhook	Yes	The company verification was rejected.

Example company progress payload

{
  "event": "company_verification.submitted",
  "data": {
    "companyVerificationId": "69d4f7657bcbe3b58b96b2f7",
    "verificationId": "cv_0b5f6f4e0aab25d8c130ab21",
    "externalId": "cv_0b5f6f4e0aab25d8c130ab21",
    "vendorData": "business_12345",
    "status": "submitted",
    "reason": "",
    "submittedAt": "2026-08-18T12:00:00.000Z",
    "campaignId": "cmp_64ff2f3f4f31d4d5f2ab1234",
    "campaignVersion": 3,
    "companyProfile": {
      "business": {
        "legalName": "Acme Limited",
        "registrationNumber": "RC123456",
        "registrationType": "private_limited_company",
        "countryOfRegistration": "NGA",
        "businessBvn": "22334455667",
        "industry": "technology",
        "description": "Cross-border payments infrastructure",
        "website": "https://acme.example"
      },
      "contact": {
        "emails": {
          "general": "hello@acme.example",
          "representative": "jane@acme.example"
        },
        "phoneNumbers": {
          "general": "+2348000000000",
          "representative": "+2348111111111"
        },
        "addresses": {
          "registered": {
            "addressLine1": "12 Marina Road",
            "city": "Lagos",
            "state": "Lagos",
            "country": "NGA",
            "fullAddress": "12 Marina Road, Lagos, Lagos, NGA"
          }
        }
      },
      "authorisedRepresentative": {
        "firstName": "Jane",
        "lastName": "Doe",
        "fullName": "Jane Doe",
        "email": "jane@acme.example",
        "phoneNumber": "+2348111111111",
        "relationshipToBusiness": "Director",
        "isAuthorised": "yes"
      },
      "officers": [
        {
          "firstName": "Jane",
          "lastName": "Doe",
          "fullName": "Jane Doe",
          "role": "director",
          "email": "jane@acme.example"
        }
      ],
      "ownership": {
        "threshold": 25,
        "beneficialOwners": []
      }
    },
    "review": {
      "source": "mixed",
      "analysisStatus": "completed",
      "pendingInternalReview": true,
      "missingFields": [],
      "reviewFlags": [],
      "provisioning": {
        "ready": false,
        "pendingFields": []
      }
    }
  }
}

For company verification events, Helium ID includes a normalized companyProfile block and a review block so downstream systems such as banking or account-opening providers can consume the important business, contact, officer, ownership, and authority details without depending on raw internal form structures. Those objects are part of the payload contract. What can vary is how complete the nested fields are at a given moment. The example above shows company_verification.submitted, but company_verification.successful is sent with the same normalized payload shape. The main differences are the event name, the status value, and the review/readiness values that reflect the final approved state.

How to decide which events to use

If you are building product logic:

use the events webhook for progress tracking
use the decision webhook for final approval or rejection handling

If you only care about final outcomes, you can listen to the decision webhook alone.

Recommended storage on your side

To make webhook handling reliable, store:

the webhook event
the webhook data
your own correlation key in vendorData
the Helium ID verification identifier
the API key environment used to create the verification

That will make retries, reconciliation, and support investigations much easier.

Signature validation

Webhook payloads are signed with HMAC-SHA256 using your API key as the secret. For implementation details, see HMAC Authentication and Endpoint Security.

Getting started

Verifications

Company Verifications

Technical Guides

Reference

Webhook destinations

Individual verification events

Example individual decision payload

Company verification events

Example company progress payload

How to decide which events to use

Recommended storage on your side

Signature validation

​Webhook destinations

​Individual verification events

​Example individual decision payload

​Company verification events

​Example company progress payload

​How to decide which events to use

​Recommended storage on your side

​Signature validation

Webhook destinations

Individual verification events

Example individual decision payload

Company verification events

Example company progress payload

How to decide which events to use

Recommended storage on your side

Signature validation