# 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-Signature` header (`t=...,v1=...`)?
* How do I handle `user.human.added` or `session.added` events 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)

```

* `t` is the Unix timestamp (seconds). Use it **as the string in the header**; never parse it and re-format it.
* `v1` is the lowercase hex HMAC-SHA256 of `"<t>.<raw body>"`, keyed with the target's `signingKey` (its UTF-8 bytes, not hex- or base64-decoded). Accept the request if **any** `v1` matches; ignore other keys such as `v0`.
* A header with no `t` fails. A missing header, malformed value or mismatch gets `401`.
* Execution kind: event executions carry `event_type`, request/response executions carry `fullMethod`, function executions carry `function`.

### Verification (Node.js)

```javascript
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)

```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_WEBHOOK_TOLERANCE_SECONDS` 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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/zitadel-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/zitadel-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/zitadel-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/zitadel-webhooks/references/overview.md).

> **For the full event reference**, see [ZITADEL: Test Actions Event](https://zitadel.com/docs/guides/integrate/actions/testing-event).

## Important Headers

| Header | Description |
| --- | --- |
| `ZITADEL-Signature` | `t=<unix seconds>,v1=<hex>[,v1=<hex>]` |

## Environment Variables

```bash
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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/zitadel-webhooks/references/overview.md) - ZITADEL webhook concepts, execution kinds, payloads, delivery
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/zitadel-webhooks/references/setup.md) - Creating a target and execution, finding the signing key
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/zitadel-webhooks/references/verification.md) - Signature verification details and gotchas