Agent skill
Prividium Webhooks Skill
Receive and verify Prividium (ZKsync) webhooks, which follow the Standard Webhooks specification. Use when setting up a Prividium event webhook or address webhook endpoint, storing the whsec_ signing key, debugging webhook-id / webhook-timestamp / webhook-signature verification, handling key rotation with several v1 signatures, or deduplicating deliveries on webhook-id.
Install this skill
npx skills add hookdeck/webhook-skills --skill prividium-webhooks
Prividium is ZKsync's private, permissioned chain product. Its webhook service sends a signed HTTPS request to your endpoint when on-chain activity matches a subscription: an event webhook watches one contract and one topic0, an address webhook watches one or more addresses. Webhooks are created in the admin UI or through /api/v1/event-webhook and /api/v1/address-webhook on your deployment's permissions API, so the sender's host differs per deployment. Signatures follow Standard Webhooks, so each delivery carries webhook-id, webhook-timestamp and webhook-signature headers.
When to Use This Skill
- How do I receive Prividium webhooks?
- How do I verify a Prividium webhook signature (
webhook-signature)? - Where do I find my Prividium signing key (
whsec_...), and why can't I read it again? - How do I accept several signatures while a Prividium signing key is being rotated?
- How do I deduplicate Prividium event webhook and address webhook deliveries?
- Why is my Prividium webhook verification failing, or failing only on retries and replays?
Verification (core)
| Header | Value |
|---|---|
webhook-id | Unique per event, stable across retries. Your idempotency key |
webhook-timestamp | Unix seconds |
webhook-signature | One or more space-separated v1,<base64> entries (several during key rotation) |
Signed content is {webhook-id}.{webhook-timestamp}.{raw body}, HMAC-SHA256, base64 output. The key is the base64-decoded part of the whsec_... secret after the prefix. Compare against every v1, entry; ignore other versions. If webhook-id is absent, read svix-id, svix-timestamp and svix-signature instead. The examples use the standardwebhooks library (npm and PyPI):
const { Webhook } = require('standardwebhooks');
// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyPrividium(rawBody, headers, secret = process.env.PRIVIDIUM_WEBHOOK_SECRET) {
const p = headers['webhook-id'] ? 'webhook' : 'svix'; // fall back to the svix-* names
new Webhook(secret).verify(rawBody, {
'webhook-id': headers[`${p}-id`],
'webhook-timestamp': headers[`${p}-timestamp`],
'webhook-signature': headers[`${p}-signature`],
}, { jsonParse: false }); // throws on a bad signature or stale timestamp → respond 401
}
The library always enforces a fixed 5-minute timestamp window, which matches Prividium's recommendation (±5 minutes). Hookdeck retries and replays resend the original webhook-timestamp, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual verifier in references/verification.md, which can drop or widen the window. In Express, read the body with express.raw({ type: '*/*' }) so any content type verifies, and parse JSON only after the check.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Event Types and Payload
Prividium's documentation does not list event type names or print the request body, so this skill doesn't invent any. What the docs do define:
- The two webhook resource types (see references/overview.md). One webhook is one subscription, so which webhook fired is a property of the endpoint (use a distinct URL per webhook), not of a header.
- Event webhooks can set
decode_events: trueto include decoded event data in deliveries. - Verify first, then parse the body defensively. The examples log whatever arrives and don't reject a verified body that isn't JSON.
Check a real delivery from your deployment (for example in the Hookdeck CLI's web UI) before writing business logic against its fields.
Delivery Semantics
Prividium states that webhook-id is stable across retries and should be your idempotency key: persist it before applying side effects and treat a repeat as a duplicate. The docs don't describe the retry schedule, a response deadline or ordering, so don't depend on any. A failed verification should get a 4xx (400 for missing headers, 401 for a bad signature) and no processing. The webhook service can suspend a webhook after repeated delivery failures or an HTTP 410 Gone; resume it with Activate in the admin UI once the endpoint is healthy.
Environment Variables
PRIVIDIUM_WEBHOOK_SECRET=whsec_xxxxx # full `signing_key` value from the create response; handlers fail closed (500) without it
# During a rotation you may list old and new keys: whsec_old,whsec_new
Local Development
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 prividium --path /webhooks/prividium
Create the webhook with the printed URL as its url (see references/setup.md) and store the signing_key from the response: it is shown once.
Reference Materials
- references/overview.md - Webhook types, headers, signing keys, delivery behaviour
- references/setup.md - Create webhooks in the UI or API, keep the signing key, rotate it
- references/verification.md - Library and manual verification, rotation, gotchas, debugging