Unique AI Documentation

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

2 min read

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 via

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

Last updated