Webhook

A webhook allows your system (e.g., backend, CRM, or back-office tools) to automatically receive onboarding results as soon as a user completes their KYC session.

We strongly recommend configuring a webhook to ensure you can:

• Capture onboarding results in real time

• Apply your own business or compliance rules (e.g., approve/reject users)

• Store and manage user verification data within your own systems

• Build automated onboarding workflows without manual intervention

⚠️ Important Hosted KYC follows the data retention policy configured for your account.

If you do not configure a webhook, and your retention policy is set not to store onboarding data, you may lose access to the results after the session is completed.

To avoid data loss, always configure a webhook to securely receive and store your onboarding results.

If your team plans to use a webhook, ask your technical team for:

• the webhook URL

• the preferred authentication method

Webhook authentication

Hosted KYC supports the following webhook authentication methods:

• None

• Basic authentication

• API key / custom header

This allows your technical team to secure the webhook in the way that best fits your internal systems.

Using a Bearer token

If your receiving system expects a Bearer token, your technical team can configure it using the API key / custom header option.

Typical setup:

• Header name: Authorization

• Token value: Bearer <your_token>

When the webhook is sent

Hosted KYC sends the webhook as soon as the onboarding session is completed.

This improves reliability because the webhook does not depend on the end-user staying on the success page or waiting for the final redirect to finish.

Webhook payload format

Hosted KYC returns the onboarding result as a JWS.

A JWS is the signed onboarding result from uqudo. Your technical team can validate it to confirm that the result came from uqudo and then read the data inside it.

If your technical team needs more detail, share these pages with them:

• Validation and Parsing

• Data Structure

• Security & Best Practices

Current JSON format

For the current Hosted KYC webhook format, the request body is a JSON object and the JWS is included in the jwsResult field.

Example:

POST https://your_webhook_url

Request body:
{
  "jwsResult": "<signed-onboarding-result>"
}

This is how the webhook should be configured and the request body that should be accepted, additional fields may be added to the JSON body over time.

Legacy format

Some existing customers may still receive the legacy webhook format where the raw JWS is sent directly as plain text in the request body.

This legacy format is deprecated.

Important migration notice Starting 10 April 2026, Hosted KYC webhook requests use the JSON format shown above.

If you are still using the legacy plain-text format, migrate to the newer webhook configuration as soon as possible.

Once the new webhook configuration is detected on your Hosted KYC setup, uqudo starts sending the JSON format automatically. No additional action is required from the uqudo side.

Retry Mechanism & Reliability

If your webhook endpoint is temporarily unavailable or fails to respond, Hosted KYC includes a retry mechanism to help ensure delivery.

• We automatically retry sending the webhook every 5 minutes

• Retries continue for up to 2 hours from the initial attempt

If the webhook is still not successfully delivered after this period, the message will be dropped.

⚠️ Important If you do not store onboarding data on uqudo (based on your data retention policy), and your webhook remains unavailable for the full retry duration, there is a risk of permanent data loss.

To avoid this, ensure that your webhook endpoint is highly available and capable of handling retries reliably.