---
title: Setup
description: What Unico needs to configure your Human Token webhook during onboarding — URL, authentication, retry, concurrency and timeout.
canonical: https://developer.unico.io/human-token/webhooks-and-events/setup
locale: en
generated_by: markdown-export
---

- [/](/)
- Additional Resources
- [Webhooks and Events](/human-token/webhooks-and-events/)
- Setup

**On this page# Setup

The Unico team configures the webhook during the integration onboarding.
### Required information​

FieldDescription**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:
StateDescription`PROCESS_STATE_FINISHED`Process finished — terminal state, regardless of outcome.
States may evolveThe 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": "humantoken"}
```

`lastEvent` and `lastEventDescription`These two fields appear in the payload **only when the process expired** before the user completed the journey. They are absent from normal completion payloads. See [Event types](/human-token/webhooks-and-events/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 fastAcknowledge 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](/human-token/webhooks-and-events/security).Last updated on Oct 17, 2026**