Skip to main content

Setup

IDCloud supports two webhook modalities, depending on how you integrate:

  • Via Portal — for Web and SDK integrations. Self-service configuration directly in the IDCloud portal.
  • By client — for API integrations using the Check orchestration capability (an asynchronous flow). Configured by the Unico team. Available in Brazil only.

To register or update your webhook endpoint, access the IDCloud portal and navigate to Settings > Webhook.

Required information​

FieldDescription
Notification URLEndpoint Unico will call to deliver event notifications. Must be reachable via HTTPS.
Authentication typeHow Unico authenticates against your endpoint. See options below.
Retry settingsMaximum number of attempts and interval between attempts (exponential backoff is applied).
Concurrency limitMaximum number of simultaneous in-flight deliveries (max: 500).
TimeoutMaximum wait time for the endpoint's response, in seconds.
Status to notifyThe 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:

StateDescription
PROCESS_STATE_FINISHEDProcess 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.

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

These two fields appear in the payload only when result = expired — that is, when the process expired before the user completed the journey. They are absent from normal completion payloads. See Event types for the full schema and the list of possible lastEvent values.

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.

Last updated on