Real-time User Sync via Zitadel Webhooks (Actions v2) — Unique AI Documentation

Real-time User Sync via Zitadel Webhooks (Actions v2)

Available from release 2026.08

Starting with release 2026.08, Unique supports real-time user synchronization via Zitadel Actions v2 webhooks. This replaces the 5-minute polling delay with near-instant event delivery (~1-3 seconds).

How it works

When enabled, the scope-management service registers itself as a webhook target with Zitadel on startup. Zitadel then sends HTTP POST requests to the scope-management service whenever user or organization events occur (e.g., user created, user deleted, profile updated, role changed).

The following events are handled in real-time:

Organization created, updated, or removed
User created (including self-registration)
User profile updated
User removed
Username changed
User metadata set or removed (including group claims)
User grant/role assignments changed

Fallback mechanism

The existing scheduled user-sync job (every 5 minutes) is kept as an automatic fallback. If the webhook delivery fails (e.g., during a service restart), the polling job catches up on missed events during its next run. A deduplication mechanism ensures that events are never processed twice, even when both the webhook and the polling job handle the same event.

Prerequisites

Zitadel v3.4.5 or later (uses the /v2beta/ Actions API)
The ZITADEL_WEBHOOK_ENDPOINT environment variable must be set on the scope-management service to the URL reachable from Zitadel (e.g., http://backend-service-scope-management:8094/webhook/zitadel-events)
ZITADEL_GRPC_HOST and ZITADEL_PAT must be configured (same as for the existing user-sync)

Note the ZITADEL_PAT must have IamOwner permissions to be able to create the actions webhook.

Configuration

Environment Variable	Required	Description
`ZITADEL_WEBHOOK_ENDPOINT`	No (opt-in)	URL that Zitadel will POST events to. Must be reachable from the Zitadel instance. When not set, only the polling sync is used.
`ZITADEL_GRPC_HOST`	Yes (existing)	Zitadel API URL
`ZITADEL_PAT`	Yes (existing)	Personal Access Token for the Zitadel service user. The service user must have the `Iam Owner` role to be able to create the actions.

No additional setup is needed in Zitadel — the service automatically registers the webhook targets and event subscriptions on startup.

Verification

On service startup, check the logs for:

Zitadel Actions v2 registration complete — confirms the webhook target was registered
Reusing existing target — on subsequent restarts, confirms the existing target is being reused
Handling webhook event — confirms events are being received in real-time

If ZITADEL_WEBHOOK_ENDPOINT is not set, the log will show:

ZITADEL_WEBHOOK_ENDPOINT not configured — skipping Actions v2 registration