Guide to Prividium Webhooks: Features and Best Practices
Prividium 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 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. Withdecode_eventson, 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:
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 gives you a public URL to register:
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 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:
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:
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 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 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 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, 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_ (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 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 records every delivery from your deployment and retries your services when they're down. Open a free account and register a Prividium source as your next webhook URL.