# Webiny Webhooks

[Webiny](https://www.webiny.com) is an open-source serverless headless CMS. Webiny 6.x can POST a JSON envelope to your endpoint when events fire in the installed apps (for example headless CMS entry events). Deliveries are signed with the Standard Webhooks scheme: `webhook-id`, `webhook-timestamp` and `webhook-signature` headers.

## When to Use This Skill

* How do I receive Webiny webhooks?
* How do I verify a Webiny webhook signature?
* Where do I find or set the Webiny webhook signing secret?
* Why does my Webiny `webhook-signature` verification fail with the `standardwebhooks` or `svix` library?
* How do I handle the Webiny webhook envelope and dedupe retries?

## Verification (core)

| Header | Value |
| --- | --- |
| `webhook-id` | Message ID (the background task ID), the same on every retry |
| `webhook-timestamp` | Unix seconds |
| `webhook-signature` | One or more space-separated `v1,<base64 HMAC-SHA256>` entries |

Signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`, HMAC-SHA256, base64 output.

**The secret is free text, not a `whsec_` value.** You choose it in the Webiny admin. Webiny's signer base64-encodes its UTF-8 bytes and adds `whsec_` before calling `standardwebhooks`, so the effective HMAC key is the secret's **raw UTF-8 bytes**. The `standardwebhooks` and `svix` libraries base64-decode the secret themselves, so verifying with them directly uses the wrong key. Implement it by hand (a secret that already starts with `whsec_` is treated as Standard Webhooks base64):

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

function verifyWebiny(rawBody /* Buffer */, h /* lower-cased headers */, secret) {
  const key = secret?.startsWith('whsec_')
    ? Buffer.from(secret.slice(6), 'base64')
    : Buffer.from(secret || '', 'utf8');
  if (!key.length) return false;                      // fail closed on an empty key
  const p = h['webhook-id'] ? 'webhook' : 'svix';     // svix-* fallback
  const [id, ts, sig] = [h[`${p}-id`], h[`${p}-timestamp`], h[`${p}-signature`]];
  if (!id || !sig || !/^[1-9][0-9]*$/.test(ts || '')) return false;
  const expected = crypto.createHmac('sha256', key)
    .update(Buffer.concat([Buffer.from(`${id}.${ts}.`), rawBody])).digest();
  return sig.split(' ').some((e) => {                 // any v1 entry; ignore v1a etc.
    const [v, s] = e.split(',');
    const got = Buffer.from(s || '', 'base64');
    return v === 'v1' && got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}

```

Python uses `hmac.new(key, f"{id}.{ts}.".encode() + raw_body, hashlib.sha256)` and `hmac.compare_digest` on bytes. No timestamp window is enforced by default, because retries and replays resend the original timestamp. Set `WEBINY_WEBHOOK_TOLERANCE_SECONDS` to opt in.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/webiny-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/webiny-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/webiny-webhooks/examples/fastapi/).

## Paste the Secret Exactly as Entered

Hookdeck's configuration alert for this source reads exactly:

> "Paste the signing secret exactly as entered: the Webiny webhook's own secret (Webiny 6), or the global webhook secret if the webhook has none. With neither set, Webiny signs with an empty key and deliveries fail verification."

Webiny signs with the webhook's own secret, else the global secret in **Webhook settings**, else an empty string. Set `WEBINY_WEBHOOK_SECRET` to whichever one applies, with no `whsec_` prefix added and no encoding.

## Event Envelope

```json
{ "id": "<task id>", "event": "<event name>", "timestamp": "2026-10-26T10:00:00.000Z",
  "webhookId": "<webhook id>", "deliveryId": "<delivery id>", "tenant": "root",
  "data": { } }

```

`id` is the background task ID and is also sent as `webhook-id`. `data` is the event payload. Deliveries are `POST` with `Content-Type: application/json`.

## Event Types

Webiny does not publish a fixed list. Events are registered at runtime by the installed Webiny apps and are listed in the admin when you create a webhook, so dispatch on the envelope's `event` string and subscribe only to what you need. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/webiny-webhooks/references/overview.md).

## Delivery Semantics

* The sender waits up to 10 minutes. Network errors, `429` and `5xx` are retried up to 3 times (1 s, 2 s, 4 s). Any other status ends the attempt, and any HTTP status at all marks the delivery "delivered" in the Webiny log, so a `4xx` is not retried.
* Deliveries can be resent from the admin. Dedupe on `webhook-id`.
* Respond `2xx` quickly and process asynchronously.

## Environment Variables

```bash
WEBINY_WEBHOOK_SECRET=...                 # signing secret as entered; handlers fail closed (500) without it
WEBINY_WEBHOOK_TOLERANCE_SECONDS=300      # optional replay window, off by default

```

## Local Development

```bash
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 webiny --path /webhooks/webiny

```

Add the printed URL as the webhook endpoint in the Webiny admin. There is no challenge handshake.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/webiny-webhooks/references/overview.md) - Envelope, event vocabulary, delivery and retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/webiny-webhooks/references/setup.md) - Creating a webhook, per-webhook vs global secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/webiny-webhooks/references/verification.md) - Key derivation, manual verification, gotchas, debugging