Webhooks

Registration

Use the link below to register a webhook endpoint. You will be prompted to sign in to your client portal account if you are not already authenticated.

Register a webhook (staging)

Select the organisation to register the webhook for, enter your HTTPS endpoint URL, and submit.

On success, two values are displayed once only. Save them immediately. They cannot be retrieved after you close the page:

• Webhook ID - required to delete this webhook in future
• Webhook Secret - unique to this registration; used to verify HMAC-SHA256 signatures on incoming requests. Not shared with any other webhook, even within the same organisation.

You can register multiple webhook endpoints per organisation. All registered endpoints receive every event.

---

Endpoint Requirements

Your endpoint must be:

• Publicly accessible from the internet over HTTPS
• Able to handle POST requests
• Responsive within 30 seconds - requests exceeding this are treated as timeouts and trigger the retry path

Signature Verification

Every request includes an X-VerifiMe-Signature header - the HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret.

Verify before processing:

1. Read the raw request body before parsing JSON
2. Compute HMAC-SHA256 of the raw body using your shared secret
3. Compare your digest with X-VerifiMe-Signature using constant-time comparison (to prevent timing attacks)
4. If the signatures do not match, return 401 and stop processing. This permanently stops delivery for that event - which is intentional.

Integration Patterns

Return 200 quickly, process asynchronously

Your endpoint must respond within 30 seconds. For most implementations, the right pattern is:

1. Verify the HMAC signature
2. Enqueue the payload for async processing
3. Return 200 immediately

Do your database writes, API calls, and business logic in the background job - not inline in the webhook handler.

Always return 200 for business logic issues

Only return non-200 for genuine technical failures or signature rejection. For everything else - unknown application references, duplicate events, records not found - return 200. Returning a 4xx (other than 408 and 429) permanently stops delivery for that event.

Use eventId for idempotency

VerifiMe may deliver the same event more than once during retries. Store processed eventId values and skip events you have already handled.

Only act on ASSESSED events

You will receive events with assessmentStatus of PENDING, PRELIMINARY, and ASSESSED. Only ASSESSED means the risk assessment is complete with a final risk level. Ignore the others.

Timing

VerifiMe processes identity documents, biometrics, and risk rules asynchronously after the customer completes data entry. You will typically receive the RISK_ASSESSMENT_UPDATED webhook within 1-3 minutes of the customer finishing the onboarding wizard.

Monitoring

• Monitor your endpoint uptime - failed deliveries are retried, but after 5 attempts the event goes to a dead-letter queue and the VerifiMe team is notified
• Alert on unexpected 401 responses - these indicate a signature mismatch and permanently stop delivery
• Use Retry-After on 429 or 503 responses to signal VerifiMe to back off for a specific duration (up to 12 hours)

For the full payload schema and retry response codes, see Risk assessment updated.

---

Deletion

To delete a webhook, use the link below. You will need the Webhook ID from registration and will be prompted to sign in if not already authenticated.

Delete a webhook (staging)

Production webhook registration and management are on the way. In the meantime, the VerifiMe support team is available at support@verifime.com for production requests, or to help recover a lost Webhook ID or Secret.