# Guide to Prividium Webhooks: Features and Best Practices

[Prividium](https://docs.prividium.zksync.io/) is ZKsync's product for running private, permissioned chains. Each deployment includes a webhook service that watches the chain and calls your endpoint when something you subscribed to happens: a specific contract emits a specific event, or a set of addresses sees activity. The service says it aims to follow the Standard Webhooks specification.

This guide explains event and address webhooks, how to create them through the admin UI or the permissions API, how signing keys and rotation work, and what Prividium leaves undocumented.

## What are Prividium webhooks?

Unlike most SaaS webhooks, Prividium's are sent by your own deployment. You manage them through that deployment's permissions API (the docs use `http://localhost:8000/api/v1`) or its admin UI, so the sending host is different for every deployment, and every management route requires authentication. The [webhooks overview](https://docs.prividium.zksync.io/developers/webhooks/overview) covers both interfaces.

There are two kinds, and each is one endpoint with exactly one subscription:

* **Event webhooks** watch one contract for one event signature, identified by `topic0`. With `decode_events` on, the service decodes the event, which requires the contract to be added in the admin UI's Contracts section first.
* **Address webhooks** watch one or more EVM addresses for activity, and you can add or remove addresses later.

Both accept an optional `from_block`.

## Prividium webhook features

| Feature | Details |
| --- | --- |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `webhook-signature` |
| Body | JSON |
| Sender | Your Prividium deployment's webhook service |
| Webhook types | Event (`contract` + `topic0`) and address (a set of EVM addresses) |
| Configuration | Admin UI or authenticated permissions API |
| Signing key | `whsec_`, one per webhook, returned once on create |
| Rotation | Overlap window set by `retire_after_secs` (default 86,400 seconds) |
| Controls | Pause and activate; automatic suspension |
| Idempotency key | `webhook-id`, stable across retries |
| Payload, retries, timeout, ordering | Not documented |

## Events and payloads

Prividium documents no event names and no delivery body. Because each webhook carries a single subscription, everything a given endpoint receives relates to that one contract event or address set, so the endpoint itself tells you what kind of notification arrived. Capture a real delivery from a test deployment before you write a parser, and validate every field you use.

The headers are documented:

| Header | Meaning |
| --- | --- |
| `webhook-id` | Unique per event, stable across retries; use it for idempotency |
| `webhook-timestamp` | Unix timestamp in seconds, for replay checks |
| `webhook-signature` | One or more space-delimited `v1,<base64>` signatures (several during rotation) |

## Setting up Prividium webhooks

You need either admin UI access or an auth token for the permissions API, and a public HTTPS URL for your receiver. For decoded event webhooks, add the contract in the admin UI first.

**In the admin UI**, open **Webhooks**, select **Add Webhook**, choose **Event** or **Address**, enter a name and URL, then either the `contract` and `topic0` (with **Decode Events** if you want it) or the addresses. Select **Create Webhook** and copy the signing key straight away; it is only shown once.

**Through the API**, replace the host with your deployment's permissions API:

```bash
curl -X POST http://localhost:8000/api/v1/event-webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "name": "My Mint Watcher",
    "url": "https://example.com/webhooks/prividium",
    "contract": "0x66EC845C0B07D1728B1b14921D561fe7963A5Ab8",
    "topic0": "0xcf3dc07771cc79f08443885798a1e22d38a980af01eb51c3fd4b475afa81467b",
    "decode_events": true
  }'

```

The response contains `endpoint.signing_key`, for example `whsec_0f71ea60...`. Store the whole value as `PRIVIDIUM_WEBHOOK_SECRET`. Address webhooks use `POST /api/v1/address-webhook` with an `addresses` array, and `/{id}/addresses` to list, add or remove addresses later. Both types support list (`limit`, `offset`), get, `PATCH` (`url`, `enabled`, and `decode_events` for event webhooks) and `DELETE`. An event webhook's contract, `topic0` and chain are fixed once created.

If the deployment can't reach your laptop directly, the [Hookdeck CLI](/docs/cli) gives you a public URL to register:

```bash
npx hookdeck-cli listen 3000 prividium --path /webhooks/prividium

```

**With Hookdeck.** Create a **Prividium** source, use its URL when you create the webhook, and paste the returned `signing_key` into the source. Prividium's guidance is to answer a failed verification with a `4xx`; Hookdeck instead answers `200` to every `POST` and records the failure on its side, without forwarding the request. Non-`POST` requests are rejected.

## Securing Prividium webhooks

The [verification page](https://docs.prividium.zksync.io/developers/webhooks/verifying-signatures) describes HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw payload>` with each signature written as `v1,<base64>`, and points to the Standard Webhooks libraries, which use the base64-decoded part of the `whsec_` key. The key's 64 hex characters are also valid base64, so libraries and the function below decode it the same way. Accept the request if any signature in the header matches:

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

With no published body, a receiver should store the verified delivery and let a worker interpret it. Giving each webhook its own path tells you which subscription a delivery belongs to:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

app.post('/webhooks/prividium/:subscription', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env[`PRIVIDIUM_SECRET_${req.params.subscription.toUpperCase()}`];
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const body = parseJsonObject(req.body);
  if (!body) return res.sendStatus(400); // signed, but not a JSON object

  const webhook_id = req.headers['webhook-id'];
  let is_new;
  try {
    is_new = await deliveries.insertIfAbsent(webhook_id, { subscription: req.params.subscription, body });
  } catch {
    return res.sendStatus(503); // not stored, so don't acknowledge
  }
  // The delivery is stored; run a periodic sweep of unprocessed rows to catch a failed notify.
  if (is_new) await worker.notify(webhook_id).catch(() => {});
  return res.sendStatus(200);
});

```

Each webhook has its own key, hence one environment variable per subscription, for example `PRIVIDIUM_SECRET_MINTS`. `deliveries` and `worker` are your own storage and job queue. Persisting `webhook-id` before acting is the pattern Prividium's [delivery handling page](https://docs.prividium.zksync.io/developers/webhooks/webhook-delivery-handling) recommends.

Prividium recommends rejecting timestamps more than five minutes from your clock, which is also the default in the Standard Webhooks libraries. Hookdeck doesn't enforce any tolerance, and it reuses the original `webhook-timestamp` when it retries or replays, so a five-minute rule would turn those deliveries away. Leave the age check out of services that only receive traffic through Hookdeck.

> **Make Prividium webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) gives a self-hosted chain's notifications a durable inbox, with every delivery stored and replayable while you learn the payload format.

## Prividium webhook limitations and pain points

### The delivery body isn't documented

**The Problem:** You can't write a parser or test fixtures from the documentation.

**Why It Happens:** Prividium's webhook pages describe management APIs, headers and signing, but show no delivery body, field list or event name.

**Workarounds:**

* Trigger the subscribed contract event or address activity on a test deployment and save the delivery.
* Store raw bodies alongside your parsed records so you can re-process them if your understanding changes.

**How Hookdeck Can Help:** Hookdeck keeps each request's headers and body, which you can inspect and [replay](/docs/retries) to an updated handler.

### Delivery policy is undocumented

**The Problem:** You don't know how long Prividium will retry or when it gives up.

**Why It Happens:** The docs say `webhook-id` stays the same across retries but give no retry schedule, timeout or ordering. They do say a webhook can be suspended after repeated delivery failures or an HTTP `410`.

**Workarounds:**

* Keep the receiver fast and available, and watch for webhooks showing **Suspended** in the admin UI.
* After fixing the cause, select **Activate**.

**How Hookdeck Can Help:** Hookdeck answers every delivery, so outages on your side don't count as failures against the webhook.

### The signing key is shown once

**The Problem:** A lost key means every delivery fails verification until you rotate.

**Why It Happens:** The key is returned only in the create response or the UI's one-time modal; reads never return it.

**Workarounds:**

* Write the key to your secret store in the same script that creates the webhook.
* If it's lost, rotate and copy the new key from the rotation response.

**How Hookdeck Can Help:** With the key saved on the Hookdeck source, only one place needs updating after a rotation.

### One subscription per webhook

**The Problem:** Watching several contracts or events means managing many webhooks and many keys.

**Why It Happens:** An event webhook covers one `contract` and one `topic0`, which can't be changed later. Address webhooks can hold many addresses, but event webhooks can't.

**Workarounds:**

* Name webhooks consistently and give each one its own path and key on your side.

**How Hookdeck Can Help:** Point several webhooks at separate Hookdeck sources and route them to one service through [connections](/docs/connections), keeping per-webhook keys out of your application.

## Best practices

### Rotate with an overlap

Use **Rotate Signing Key** or `POST /api/v1/event-webhook/<ENDPOINT_UUID>/signing-keys/rotate` (or `/address-webhook/...`) with `retire_after_secs`. Store the new key, deploy a verifier that tries both keys, wait for the old one to retire, then remove it. During the overlap each delivery carries two `v1,` signatures.

### Pause instead of deleting

**Pause** stops deliveries and keeps the subscription. Deleting removes the webhook, and a new one gets a new key.

### Deduplicate durably

Record `webhook-id` before applying side effects, and keep handlers safe to re-run. Our [guide to webhook idempotency](/webhooks/guides/implement-webhook-idempotency) covers storage options.

### Watch for lost chain permission

Prividium can suspend a webhook when chain permission is lost. If deliveries stop after a permissions change, check the webhook's status before debugging your receiver.

## Conclusion

Prividium's webhooks bring on-chain activity from a private ZKsync chain to your services with Standard Webhooks signatures. Treat the signing key as a one-time secret, keep one path and key per subscription, deduplicate on `webhook-id`, and capture real payloads, because the documentation doesn't include any.

[Hookdeck Event Gateway](https://hookdeck.com) records every delivery from your deployment and retries your services when they're down. [Open a free account](https://dashboard.hookdeck.com/signup) and register a Prividium source as your next webhook URL.