Guide to ZITADEL Webhooks: Features and Best Practices
ZITADEL is an open-source identity platform, available as a cloud service or self-hosted, for user management, login and single sign-on. Its Actions v2 feature calls your HTTP endpoints, called targets, when something happens in an instance: a user is added, a session starts, or an API method is called. That lets you sync users to a CRM, write audit logs or add claims to tokens.
This guide covers ZITADEL targets and executions, the different payloads each execution sends, verifying ZITADEL-Signature with a target's signingKey, and how target types change what your response does.
What are ZITADEL webhooks?
Actions v2 has two parts. A target describes an endpoint: its URL, timeout, payload type and how ZITADEL treats the response. An execution links a condition to one or more targets. What you receive depends on that condition:
| Execution kind | Condition | Payload identifies it by |
|---|---|---|
| Event | event (an event type, e.g. user.human.added) | event_type |
| Request / response | request or response (a gRPC method) | fullMethod |
| Function | function (e.g. preuserinfo) | function |
Targets come in three types. A restWebhook target uses only your response status, a restCall target uses the status and the response body, and a restAsync target uses neither and can be called in parallel with other targets. With interruptOnError, a status of 400 or above stops the execution and no further targets are called.
Only targets with payloadType set to PAYLOAD_TYPE_JSON are signed with the ZITADEL-Signature header and covered by the linked skill. JWT and JWE payload types are verified against the instance's keys instead and aren't supported.
ZITADEL webhook features
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | zitadel-signature |
| Body | JSON |
| Event routing | Body field event_type |
From ZITADEL's actions usage guide:
- Each target has its own
timeout, such as"10s". - Each target has its own signing key, returned when you create it and regenerated when you patch it.
- Setting up targets and executions needs at least the
IAM_OWNERrole. - Retries aren't documented.
Events and payloads
For event executions, route on event_type.
| Event | event (an event type, e.g. user.human.added) | event_type | | Request / response | request or response (a gRPC method) | fullMethod | | Function | function (e.g. preuserinfo) | function |
These are event types you can put in an execution's event condition. ZITADEL's events reference lists the rest.
An event execution sends aggregateID, aggregateType, resourceOwner, instanceID, version, sequence, event_type, created_at, userID (who caused the event) and event_payload. Request and response executions send fullMethod, instanceID, orgID, projectID, userID, request and, for responses, response. ZITADEL suggests reading request and response with a protobuf-aware library such as protojson, because they're protocol buffer messages. Function executions send function-specific data, such as the userinfo claims for preuserinfo.
The docs show these bodies with typed placeholders rather than real values, so capture a real delivery before relying on any field.
Setting up ZITADEL webhooks
The signing key is generated per target and returned when you create the target:
curl -L -X POST "https://${CUSTOM_DOMAIN}/v2/actions/targets" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer <TOKEN>" \
--data-raw '{
"name": "my webhook",
"restWebhook": { "interruptOnError": true },
"endpoint": "https://your-endpoint.example.com/webhooks/zitadel",
"timeout": "10s",
"payloadType": "PAYLOAD_TYPE_JSON"
}'
{ "id": "344649040681500814", "creationDate": "2025-10-31T15:00:36.432595Z", "signingKey": "somekey" }
Store signingKey as ZITADEL_SIGNING_KEY. Then link the target to a condition with an execution:
curl -L -X PUT "https://${CUSTOM_DOMAIN}/v2/actions/executions" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer <TOKEN>" \
--data-raw '{
"condition": { "event": { "event": "user.human.added" } },
"targets": ["<TargetID returned>"]
}'
Other conditions: {"request": {"method": "/zitadel.user.v2.UserService/CreateUser"}}, {"response": {...}} and {"function": {"name": "preuserinfo"}}.
Only Actions v2 targets with the JSON payload type are supported. JWT and JWE payload types aren't.
To route through Hookdeck, create a ZITADEL source with the target's signingKey and use its URL as the target endpoint. For local development:
npx hookdeck-cli listen 3000 zitadel --path /webhooks/zitadel
Securing ZITADEL webhooks
ZITADEL-Signature has the form t={unix timestamp},v1={signature}. The signature is the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the target's signingKey. Check every v1 value, not just the first: ZITADEL's Go signing code can produce one per key.
ZITADEL says the timestamp can be used to time out requests, and the zitadel-go validator rejects anything older than 300 seconds by default. The verifier below doesn't apply a tolerance, and Hookdeck doesn't either. If you add one to a direct receiver, note that a replay from Hookdeck keeps the original timestamp.
Node.js verification
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['zitadel-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const parts = signature.split(',').map((part) => part.trim());
const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The handler accepts event and request/response bodies, deduplicates events on the aggregate and sequence, and queues the rest.
const express = require('express');
const app = express();
app.post('/webhooks/zitadel', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.ZITADEL_SIGNING_KEY;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
let call;
try {
call = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!call || typeof call !== 'object' || Array.isArray(call)) return res.sendStatus(400);
const isEvent = typeof call.event_type === 'string';
if (!isEvent && typeof call.fullMethod !== 'string') return res.sendStatus(400);
try {
if (isEvent) {
const key = [call.instanceID, call.aggregateID, call.sequence].map(String).join(':');
if (await alreadyHandled(key)) return res.sendStatus(200);
await queue.add('zitadel-event', {
type: call.event_type,
aggregateType: call.aggregateType,
aggregateId: call.aggregateID,
payload: call.event_payload,
});
await markHandled(key);
} else {
await queue.add('zitadel-call', { method: call.fullMethod, userId: call.userID, orgId: call.orgID });
}
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
Replace queue, alreadyHandled and markHandled with your own job queue and deduplication store. event_payload may be an object or a base64 string, so check its type in the worker. Function executions such as preuserinfo expect a response body from a restCall target, so give them their own handler.
Hookdeck performs the same check when you use its ZITADEL source type. Instead of a 401, ZITADEL receives 200, and the failed check is recorded on the request in Hookdeck. Hookdeck applies no timestamp window.
Make ZITADEL webhooks production-ready. Hookdeck Event Gateway keeps every ZITADEL event and retries your service when it's down, which ZITADEL doesn't document doing.
ZITADEL webhook limitations and pain points
Retries aren't documented
The Problem: If your endpoint fails, you can't tell whether ZITADEL will send the event again.
Why It Happens: The actions pages describe timeouts and interruptOnError, but not retries.
Workarounds:
- Treat each call as possibly the only one, and store it before responding.
- Reconcile users and sessions through the ZITADEL API after an outage.
How Hookdeck Can Help: Hookdeck stores each call on arrival and retries your service under a policy you choose.
Your status can block user actions
The Problem: An error from your endpoint can stop a request execution, such as user creation, if the target has interruptOnError.
Why It Happens: With interruptOnError, a status of 400 or above interrupts the execution.
Workarounds:
- Use
restAsyncor a webhook withoutinterruptOnErrorfor notifications that shouldn't block anything. - Keep
interruptOnErrorfor targets that are meant to enforce a policy.
How Hookdeck Can Help: For notification targets, Hookdeck answers 200 straight away, so outages on your side don't feed back into ZITADEL.
No event type list or real examples
The Problem: You have to look elsewhere for event types, and the payload docs use placeholders.
Why It Happens: The actions pages point to the general events documentation and show typed placeholders, not deliveries.
Workarounds:
- Trigger each event you care about in a test instance and save the delivery.
- Check field types, especially
event_payload, before use.
How Hookdeck Can Help: Hookdeck keeps every delivered body, so you can inspect real events and replay them against your code.
Only JSON targets are signed with HMAC
The Problem: JWT and JWE targets don't carry ZITADEL-Signature.
Why It Happens: Those payload types are signed or encrypted with instance keys instead.
Workarounds:
- Set
payloadTypetoPAYLOAD_TYPE_JSONexplicitly on webhook targets. - Verify JWT targets against the instance's keys if you need them.
How Hookdeck Can Help: Hookdeck's ZITADEL source verifies JSON targets, and records requests from other payload types as failed verification.
Best practices
One target per purpose
Each target has its own key and timeout. Separate targets for notifications and policy checks keep a slow analytics endpoint from affecting logins.
Deduplicate on aggregate and sequence
aggregateID and sequence together identify an event within an instance. Webhook idempotency covers the options.
Rotate keys by patching
Patching a target regenerates its signingKey. Update your stored key, and any Hookdeck source, at the same time.
Respond within the target timeout
Queue and respond, then process. More on this in why to process webhooks asynchronously.
Conclusion
ZITADEL Actions v2 calls your targets for events, API requests and responses, and functions, signing JSON payloads with t= and v1= in ZITADEL-Signature using each target's signingKey. Pick the target type to match whether your response should matter, check every v1, and plan your own retries.
Hookdeck Event Gateway verifies ZITADEL calls, keeps them and retries delivery to your services.
Get started with Hookdeck for free and handle ZITADEL webhooks reliably in minutes.