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)

HeaderValue
webhook-idUnique per event, stable across retries. Your idempotency key
webhook-timestampUnix seconds
webhook-signatureOne 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: true to 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →