Webhooks and Events
A webhook is a systemic notification service that allows asynchronous integration between systems — Unico IDCloud notifies your backend whenever a process changes state, so you don't need to poll for updates.
This section covers the four things you need to integrate webhooks: how to set up the endpoint and authentication, the events Unico sends, the fallback strategy, and the security and reliability patterns your endpoint must implement.
When to use webhooks
Webhooks are the recommended way to be notified of process completion. They are particularly relevant for:
- Human Token Journey (
humantoken,humantoken+revalidation) — to be notified when the user finishes the journey of a process created with Create Process. Webhooks fire only at terminal state (PROCESS_STATE_FINISHED); no intermediate progress events are delivered. - API Only flows (
api+humantoken,api+liveness+humantoken,api+liveness+humantoken+revalidation) — the result already comes in the Create Process response, so these flows do not depend on the webhook.
Webhooks complement, but do not replace, the GetProcess endpoints. See Fallback.
In this section
- Setup — endpoint registration, authentication methods (OAuth2, Basic, API Key), retry settings.
- Event types — the events Unico sends and the payload structure.
- Security — idempotency, concurrency limit, and error rate.
- Fallback — how to retrieve the process result when the webhook is unavailable.