Agent skill
ZITADEL Webhooks Skill
Receive and verify ZITADEL webhooks (Actions v2 targets with the JSON payload type). Use when setting up ZITADEL webhook handlers, debugging ZITADEL-Signature verification, or handling events like user.human.added and session.added, or request, response and function executions.
Install this skill
npx skills add hookdeck/webhook-skills --skill zitadel-webhooks
Only Actions v2 targets with the JSON payload type are supported. JWT and JWE payload types aren't.
When to Use This Skill
- How do I receive ZITADEL webhooks (Actions v2 targets)?
- How do I verify the
ZITADEL-Signatureheader (t=...,v1=...)? - How do I handle
user.human.addedorsession.addedevents from ZITADEL? - How do I handle ZITADEL request, response and function executions?
- Why is my ZITADEL webhook signature verification failing?
Essential Code (USE THIS)
ZITADEL signs every JSON-payload target request with ZITADEL-Signature:
ZITADEL-Signature: t=1700000000,v1=3c5a...e91f
ZITADEL-Signature: t=1700000000,v1=3c5a...e91f,v1=77b0...42d8 (one v1 per signing key)
tis the Unix timestamp (seconds). Use it as the string in the header; never parse it and re-format it.v1is the lowercase hex HMAC-SHA256 of"<t>.<raw body>", keyed with the target'ssigningKey(its UTF-8 bytes, not hex- or base64-decoded). Accept the request if anyv1matches; ignore other keys such asv0.- A header with no
tfails. A missing header, malformed value or mismatch gets401. - Execution kind: event executions carry
event_type, request/response executions carryfullMethod, function executions carryfunction.
Verification (Node.js)
const crypto = require('crypto');
// rawBody: Buffer of the exact request bytes (express.raw({ type: '*/*' }), not express.json)
function verifyZitadel(rawBody, signatureHeader, secret) {
if (!secret || !signatureHeader) return false;
let timestamp;
const signatures = [];
for (const item of signatureHeader.split(',')) {
const i = item.indexOf('=');
if (i <= 0) continue;
const key = item.slice(0, i).trim(), value = item.slice(i + 1).trim();
if (key === 't' && timestamp === undefined) timestamp = value;
else if (key === 'v1') signatures.push(value);
}
if (!timestamp || signatures.length === 0) return false;
// Optional replay window, off by default: retries and replays keep the original timestamp
const expected = crypto.createHmac('sha256', Buffer.from(secret, 'utf8'))
.update(Buffer.concat([Buffer.from(`${timestamp}.`), rawBody])).digest();
return signatures.some((sig) => {
if (!/^[0-9a-fA-F]{64}$/.test(sig)) return false; // validate before decoding
return crypto.timingSafeEqual(Buffer.from(sig.toLowerCase(), 'hex'), expected);
});
}
Verification (Python)
import hashlib, hmac, re
def verify_zitadel(raw_body: bytes, signature_header, secret: str) -> bool:
if not secret or not signature_header:
return False
timestamp, signatures = None, []
for item in signature_header.split(","):
key, sep, value = item.partition("=")
key, value = key.strip(), value.strip()
if key == "t" and sep and timestamp is None:
timestamp = value
elif key == "v1" and sep:
signatures.append(value)
if not timestamp or not signatures:
return False
expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).digest()
return any(
re.fullmatch(r"[0-9a-fA-F]{64}", s) and hmac.compare_digest(bytes.fromhex(s), expected)
for s in signatures
)
ZITADEL does not document a replay window or retries. The examples do not reject old timestamps by default, because Hookdeck retries and replays resend the original headers and timestamp. Set ZITADEL_ to a positive number of seconds to opt in (t is Unix seconds); unset or 0 leaves it off.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Common Event Types
Event executions carry the type in event_type, plus aggregateType, aggregateID and a base64-encoded JSON event_payload. You choose which events to send by creating an execution with an event condition.
| Event | Description |
|---|---|
user.human.added | A human user was created (event_payload has userName, firstName, lastName, email, ...) |
session.added | A session was created |
Request and response executions carry fullMethod (for example /zitadel.user.v2.UserService/CreateUser); function executions carry function (for example function/preuserinfo). Handlers should dispatch on whichever field is present and treat every field as untrusted input. See references/overview.md.
For the full event reference, see ZITADEL: Test Actions Event.
Important Headers
| Header | Description |
|---|---|
ZITADEL-Signature | t=<unix seconds>,v1=<hex>[,v1=<hex>] |
Environment Variables
ZITADEL_WEBHOOK_SECRET=your_target_signing_key # signingKey returned when the target is created
ZITADEL_WEBHOOK_TOLERANCE_SECONDS=0 # optional; a positive value opts in to the replay window
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 zitadel --path /webhooks/zitadel
In Hookdeck, the source type is ZITADEL. Its setup note, which applies here too: Only Actions v2 targets with the JSON payload type are supported. JWT and JWE payload types aren't.
Reference Materials
- references/overview.md - ZITADEL webhook concepts, execution kinds, payloads, delivery
- references/setup.md - Creating a target and execution, finding the signing key
- references/verification.md - Signature verification details and gotchas