# Prividium Webhooks

[Prividium](https://docs.prividium.zksync.io) 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):

```javascript
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/prividium-webhooks/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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/prividium-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/prividium-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/prividium-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/prividium-webhooks/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

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

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/prividium-webhooks/references/setup.md)) and store the `signing_key` from the response: it is shown once.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/prividium-webhooks/references/overview.md) - Webhook types, headers, signing keys, delivery behaviour
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/prividium-webhooks/references/setup.md) - Create webhooks in the UI or API, keep the signing key, rotate it
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/prividium-webhooks/references/verification.md) - Library and manual verification, rotation, gotchas, debugging