Webhook

Overview

The Webhook (aka: Global Webhook) lets you receive the result of every onboarding session straight to an endpoint of your choice, no matter how that session was started.

Onboarding sessions include "Enrollment Flow", "NFC / Reading Flow", and "Lookup Flow".

Whether your users go through a Hosted KYC flow, your own mobile app using the Uqudo SDK, or any other integration method, the result is always delivered to the same place.

---

When should I use it?

Situation	Use Global Webhook
You use the Uqudo SDK directly (not Hosted KYC) and need to receive onboarding results server-side	✅ Yes
You have multiple Hosted KYC configurations and want all results going to one endpoint instead of repeating the same webhook URL in every config	✅ Yes
You want a single, centralised receiver for all onboarding activity across your account	✅ Yes
You only have one Hosted KYC configuration and already have a webhook configured there	⚠️ Optional, see Using both

---

How it works

Once configured, whenever an onboarding session completes for your account, Uqudo sends an HTTP POST request to your endpoint with the session result.

The request body is a JSON object:

{
  "jwsResult": "<signed JWT string>"
}

The jwsResult is a signed JWT containing the full onboarding data. You can verify its signature using Uqudo's public key and then decode the payload to access the result.

---

Difference from the Hosted KYC webhook

You may already be familiar with the webhook that can be set per Hosted KYC configuration. Here is how they compare:

	Hosted KYC Webhook	Global Webhook
Scope	One specific Hosted KYC configuration	All onboarding sessions across your entire account
Works with the Uqudo SDK	❌ No	✅ Yes
Configuration	Per Hosted KYC config	Once per account

In short: the Hosted KYC webhook is tied to a specific flow configuration. The Global Webhook is account-wide and method-agnostic.

---

Using both (Global and Hosted KYC webhook)

You can run both at the same time. They are completely independent, one does not replace or affect the other.

⚠️ Important: if you configure the same endpoint URL in both your Global Webhook and a Hosted KYC configuration, your endpoint will receive two identical notifications for every session that goes through that Hosted KYC flow. This is by design.

If you only want one delivery per session, either:

• Remove the webhook from the individual Hosted KYC configuration and rely solely on the Global Webhook, or

• Keep the per-config webhook and do not set a Global Webhook.

---

Configuring the Global Webhook

You can manage the Global Webhook from the Customer Portal under Development → Webhook.

You can only have one Global Webhook per account. Saving a new configuration always replaces the previous one.

Security options

Security Type	When to use
NONE	No authentication: your endpoint is publicly accessible or protected by network controls
BASIC_AUTHENTICATION	HTTP Basic Auth: provide a username and password that Uqudo will include in every request
CUSTOM_HEADERS	Inject one or more custom HTTP headers (e.g. X-Api-Key): useful for API gateway tokens

Configuration fields

Field	Required	Description
url	✅ Always	The HTTPS endpoint that will receive the onboarding result
securityType	✅ Always	One of NONE, BASIC_AUTHENTICATION, CUSTOM_HEADERS
userId	When securityType is BASIC_AUTHENTICATION	Basic Auth username
password	When securityType is BASIC_AUTHENTICATION	Basic Auth password
customHeaders	When securityType is CUSTOM_HEADERS	List of headers (1–5), each with a name and value

---

Receiving and validating results

When your endpoint receives a request:

1. Verify the signature of the jwsResult JWT using Uqudo's public key to confirm the payload has not been tampered with.

2. Decode the JWT payload to access the onboarding result data (document scan, face verification, background check, etc.).

3. Extract the session ID from the jti claim if you need to correlate the result back to a session in your system.

4. Return a 2xx response as quickly as possible. If your endpoint is slow or returns a non-2xx status, Uqudo will retry delivery automatically.

Your endpoint should be idempotent, i.e. processing the same session ID twice should have no unintended side effects, in case a retry delivers the result more than once.

---

Retry behaviour

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.

---

Deleting the Global Webhook

Removing the Global Webhook stops future deliveries immediately. Sessions that are already in flight at the time of deletion may still attempt delivery once before the change takes effect.