# 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](https://zitadel.com/docs/guides/integrate/actions/usage):

* 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_OWNER` role.
* 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**:

```bash
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"
  }'

```

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

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

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

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

```javascript
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](/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 `restAsync` or a webhook without `interruptOnError` for notifications that shouldn't block anything.
* Keep `interruptOnError` for 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 `payloadType` to `PAYLOAD_TYPE_JSON` explicitly 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](/webhooks/guides/implement-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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## 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](https://hookdeck.com) verifies ZITADEL calls, keeps them and retries delivery to your services.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle ZITADEL webhooks reliably in minutes.