Skip to main content
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.

​
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
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.

​
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.