Webhooks and Events

MarkdownChatGPTClaude

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:

• Asynchronous Web & SDK flows — to be notified when a POST /client/v1/process finishes processing on Unico's side.
• Long-running flows that combine multiple capabilities (e.g., document analysis + manual review). Webhooks fire only at terminal state (PROCESS_STATE_FINISHED); no intermediate progress events are delivered.

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.