Setup

To configure a webhook on Unico IDCloud, provide your endpoint, the authentication method, and the retry policy. Configuration is done by the Unico team — contact your CS / Onboarding team to register or update a webhook.

Required information

Field	Description
Notification URL	Endpoint Unico will call to deliver event notifications. Must be reachable via HTTPS.
Authentication type	How Unico authenticates against your endpoint. See options below.
Retry settings	Maximum number of attempts and interval between attempts (exponential backoff is applied).
Concurrency limit	Maximum number of simultaneous in-flight deliveries (max: 500).
Timeout	Maximum wait time for the endpoint's response, in seconds.
Status to notify	The set of process states that trigger a notification. Currently fixed to PROCESS_STATE_FINISHED; not configurable at this time.

Authentication methods

OAuth2

Provide:

• Webhook endpoint
• OAuth2 provider URL
• OAuth2 provider ClientId
• OAuth2 provider Secret

Unico will request an access token from the provider URL using the client credentials and forward it to your endpoint as a Bearer token.

Basic Authorization

Provide credentials in the format user:pass. Unico encodes them in Base64 and sends them in the Authorization: Basic <encoded> header on every webhook call.

API Key

Two formats are supported. The string is split on the first colon:

• header:value — sets a custom header name. Examples:
  • X-API-Key:abc123 → X-API-Key: abc123
  • Authorization:Bearer abc123 → Authorization: Bearer abc123
• value only (no colon) — the value is sent as the Authorization header with no scheme prefix. Example: abc123 → Authorization: abc123.

Use the header:value format when you need a Bearer scheme (e.g., Authorization:Bearer <token>); the value-only format sends the raw value without a prefix.

No authentication

No credentials are sent. Only recommended for development environments — production endpoints should always require authentication.

Process states that trigger notifications

Currently, Unico sends a notification whenever a process transitions to:

State	Description
PROCESS_STATE_FINISHED	Process finished — terminal state, regardless of outcome.

States may evolve

The set of states notified by the platform may change in the future. Make the states your endpoint reacts to configurable, so adding a new state does not require redeploying your service.

Request format

Webhook deliveries are POST requests to your endpoint. The body contains the process identifier and current state. All fields are mandatory.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id",
  "lastEvent": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

For the full payload schema and the list of lastEvent values, see Event types.

Expected response

Your endpoint must respond synchronously:

• Success: any HTTP status in the 200–299 range.
• Failure: any other status. Unico will retry with exponential backoff up to the configured maximum number of attempts, or until a 2xx is received.

Respond fast

Acknowledge the webhook quickly (under your configured timeout) and process the payload asynchronously on your side. Long-running processing inside the webhook handler increases the chance of timeouts and unnecessary retries.

For idempotency and retry handling guidance, see Security.