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

# Troubleshooting

> Common integration issues for Helium ID verification flows and how to diagnose them quickly.

This guide covers the most common issues teams hit when integrating Helium ID.

## I am not receiving webhooks

Check these first:

1. Confirm the API key has the correct **events** and **decision** webhook URLs configured.
2. Confirm your endpoint is publicly reachable.
3. Confirm your server returns a `2xx` response quickly after receiving the webhook.
4. Confirm you are listening for the right event names.
5. Confirm you are testing with the expected API key environment.

Helpful dashboard checks:

* open **Events** to see whether the event was created
* open **Webhooks** to inspect delivery attempts and failures

If the event exists but the webhook was not delivered, the issue is usually with the webhook URL or the receiving server.

## The webhook signature does not validate

Common causes:

* using the wrong API key as the HMAC secret
* hashing a parsed JSON object instead of the raw request body
* missing the exact `Webhook-Timestamp` header value
* modifying whitespace or key order before hashing

Make sure you:

1. read the raw request body
2. build the signature payload as `{timestamp}.{rawBody}`
3. hash it with HMAC-SHA256 using the API key as the secret
4. compare it to `Webhook-Signature` using a timing-safe comparison

See [HMAC Authentication and Endpoint Security](/technical/hmac).

## My company verification is stuck in `started`

This usually means the representative began the hosted flow but has not completed and submitted it yet.

Check:

1. whether all required company documents were uploaded
2. whether all required flow sections were completed
3. whether the authorising-person liveness step is still pending

Once the representative submits successfully, the verification should move to `submitted` and emit `company_verification.submitted`.

## My company verification is `submitted` but there is no final decision yet

That is expected until review completes.

Typical reasons:

* the case is waiting for review
* the case has not yet been moved to `under review`
* you are testing a flow and have not advanced the decision in the test dashboard flow

Remember:

* **test company verifications** can be moved through review states by the customer admin dashboard
* **live company verifications** are decided by Helium ID internally

## The hosted link does not open

For individual verifications:

* confirm you are using the exact `data.link` returned by the create endpoint

For company verifications:

* confirm the URL still contains both `processId` and `hostedToken`
* confirm the hosted link has not expired
* confirm you did not rebuild the URL manually

If a company hosted link has expired, generate a new secure link from the dashboard.

## `GET /v1/verifications/{id}` returns not found

Check:

1. that you are using the individual verification ID, not a company verification public ID
2. that the verification belongs to the same API key
3. that the verification has not been deleted

Company verifications do not currently expose a public fetch endpoint, so a company verification ID cannot be fetched through the individual verification API.

## I can update a test company verification, but not a live one

That is expected behavior.

Customer-admin review and terminal status updates are limited to company verifications created with a **test API key**.

Live company verification terminal decisions are reserved for Helium ID internal review.

## I am seeing the wrong ID in webhooks

This is usually an ID-mapping issue:

* individual verification webhooks use `verificationId`
* company verification webhooks use `companyVerificationId` for the internal record
* company verification webhooks also include `externalId`, which is the public company verification ID

See [IDs and Terminology](/reference/ids-and-terminology).

## I do not know whether I should listen to the events webhook or the decision webhook

Use:

* **events webhook** for progress updates
* **decision webhook** for terminal approval or rejection handling

If you only care about final outcomes, the decision webhook is the most important one to implement first.

## Quick support checklist

When debugging an integration issue, collect:

* API key environment used
* verification type: individual or company
* your `vendorData`
* Helium ID verification ID
* event name
* raw webhook payload
* webhook response status from your server

That short checklist usually makes it much faster to trace the problem end to end.