# 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](https://docs.uqudo.com/docs/kyc/uqudo-sdk/sdk-result/validation-and-parsing)
* [Data Structure](https://docs.uqudo.com/docs/kyc/uqudo-sdk/sdk-result/data-structure)
* [Security & Best Practices](https://docs.uqudo.com/docs/kyc/uqudo-sdk/sdk-result/security-and-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`

```json
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uqudo.com/docs/kyc/no-code-kyc/webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.