# Guide to Webiny Webhooks: Features and Best Practices

[Webiny](https://www.webiny.com) is an open-source headless CMS that you deploy to your own AWS account. In Webiny 6, webhooks let content changes reach the rest of your stack: rebuild a static site when an entry is published, purge a CDN, or keep a search index in sync. Each webhook is configured in the Webiny admin, and Webiny signs every delivery using the Standard Webhooks scheme.

## What are Webiny webhooks?

A Webiny webhook has an endpoint URL, a set of subscribed events and an optional signing secret. When a subscribed event fires, Webiny queues a background task that posts a JSON body to your URL with `webhook-id`, `webhook-timestamp` and `webhook-signature` headers. Webiny's [webhook reference](https://www.webiny.com/docs/reference/sdk/webhooks) covers verification with `createVerifyWebhookPayload` from `@webiny/sdk/webhooks`.

The signing secret is the unusual part. You type it yourself, and it isn't a `whsec_` key.

## Webiny webhook features

| Feature | Details |
| --- | --- |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `webhook-signature` |
| Body | JSON |
| Event routing | Body field `event` |

## Events and payloads

Webiny doesn't publish a fixed list of events. Each installed app registers its own when Webiny starts, and the admin shows the available events for your installation when you create a webhook:

| Where it comes from | Example use |
| --- | --- |
| Headless CMS apps (entry lifecycle events) | Rebuild a static site, purge a CDN, sync to search |
| Other installed apps | Whatever the app registers |

Webiny's docs don't show a payload either. In the 6.5.0 `@webiny/webhooks` package source, the body has these top-level fields:

| Field | Meaning in the 6.5.0 source |
| --- | --- |
| `id` | The background task's ID, also sent as `webhook-id` |
| `event` | The event name |
| `timestamp` | When the event was sent |
| `webhookId` | The webhook configuration that matched |
| `deliveryId` | The delivery record |
| `tenant` | The Webiny tenant |
| `data` | The event's payload |

Treat these as a guide rather than a contract, and log a real delivery of each event you subscribe to before relying on `data`.

## Setting up Webiny webhooks

Start by deciding on the signing secret. Webiny chooses it in this order:

1. the webhook's own signing secret;
2. the global signing secret in **Webhook settings**;
3. an empty string, which means deliveries can't be verified.

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.

Then register the endpoint:

1. In the Webiny admin, open the webhooks settings and create a webhook.
2. Enter the endpoint URL, for example `https://your-app.com/webhooks/webiny`.
3. Choose events from the list the admin shows.
4. Enter a signing secret, or leave it empty to use the global one.
5. Save, and store the same string in your receiver's environment, with no `whsec_` prefix and no encoding:

```bash
WEBHOOK_SECRET=<secret exactly as entered>

```

To put Hookdeck in front, create a source with the **Webiny** type, enter the same secret, and use the source URL as the endpoint. The [Hookdeck CLI](/docs/cli) forwards it locally:

```bash
npx hookdeck-cli listen 3000 webiny --path /webhooks/webiny

```

The admin can resend a delivery, which is an easy way to send a test without editing content.

## Securing Webiny webhooks

Webiny signs `webhook-id`, a dot, `webhook-timestamp`, another dot and the raw body with HMAC-SHA256, and sends the result as one or more `v1,` entries in `webhook-signature`. In the package source, a secret that doesn't start with `whsec_` is base64-encoded and given that prefix before signing, so the effective key is the secret's own UTF-8 bytes. The function below uses those bytes, base64-decodes a `whsec_` value if you have one, and also accepts `svix-*` header names:

```javascript
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 = secret.startsWith('whsec_')
    ? decodeBase64(secret.slice(6)) : Buffer.from(secret, 'utf8');
  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);
  });
}

```

Don't hand a plain-text Webiny secret to a generic Standard Webhooks library that expects base64 after `whsec_`. Webiny's own `createVerifyWebhookPayload` uses the `standardwebhooks` library, which rejects timestamps outside its tolerance window. Hookdeck applies no tolerance and keeps the original `webhook-timestamp` when it retries or replays, so behind Hookdeck the function above skips the age check.

The receiver stores each delivery and routes on `event` in a worker:

```javascript
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;
  }
}

// contentEvents.save(deliveryKey, event) stores the delivery once and resolves when durable.
function createWebinyReceiver(contentEvents) {
  const app = express();
  app.post('/webhooks/webiny', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.WEBINY_WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500); // an empty secret means Webiny signed with an empty key
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

    const event = parseJsonObject(req.body);
    if (!event) return res.sendStatus(400); // signed, but not a JSON object
    try {
      await contentEvents.save(req.headers['webhook-id'] || req.headers['svix-id'], event);
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

```

A Hookdeck Webiny source sends `200` back to Webiny whatever the signature, and records a mismatch as failed verification without forwarding it.

> **Make Webiny webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) gives Webiny's short retry window a durable queue behind it and fans one content event out to build, cache and search services.

## Webiny webhook limitations and pain points

### Retries end within seconds

**The Problem:** A content change made while your builder was restarting never triggers a rebuild.

**Why It Happens:** Webiny's docs don't state a retry policy. The 6.5.0 package source retries network errors, `429` and `5xx` responses up to three times, after 1, 2 and 4 seconds, honouring `Retry-After`. Any other status ends the attempt, and the delivery log marks any HTTP response as delivered.

**Workarounds:**

* Keep the receiver up and quick to respond, and resend failed deliveries from the admin.

**How Hookdeck Can Help:** Hookdeck accepts each delivery when Webiny sends it and [retries](/docs/retries) your service for as long as you configure.

### No event list or example payloads

**The Problem:** You can't write handlers from the docs alone.

**Why It Happens:** Events are registered at runtime by each installed app, and the docs cover verification only.

**Workarounds:**

* Read the events offered in your admin, subscribe to a few, and capture their bodies.

**How Hookdeck Can Help:** Hookdeck stores every request it receives, so you can inspect real Webiny bodies before writing code.

### The secret can silently be empty

**The Problem:** Every delivery fails verification after an install that never set a secret.

**Why It Happens:** With no webhook secret and no global secret, Webiny signs with an empty key.

**Workarounds:**

* Set a global secret in **Webhook settings** as a default, and refuse to start a receiver with an empty secret, as the code above does.

**How Hookdeck Can Help:** Hookdeck flags each failed verification in its request log, so a missing secret shows up on the first delivery.

### The secret isn't a Standard Webhooks key

**The Problem:** Off-the-shelf Standard Webhooks code rejects every request.

**Why It Happens:** Webiny secrets are free text, used as raw bytes, rather than `whsec_` base64.

**Workarounds:**

* Use Webiny's SDK, a verifier that handles plain-text secrets like the one above, or base64-encode the secret and add `whsec_` before passing it to a generic library.

**How Hookdeck Can Help:** The Hookdeck Webiny source takes the secret exactly as entered.

## Best practices

### Set a global secret

A global secret in **Webhook settings** means a new webhook is never left unsigned. Give individual webhooks their own secrets when different teams own the receivers.

### Debounce rebuilds

Editors can save and publish many entries in a row. Queue site rebuilds and run one for a burst of events instead of one per delivery.

### Scope by tenant

If you run multiple tenants, check `tenant` before acting on an event so one tenant's change doesn't rebuild another's site.

### Deduplicate deliveries

Webiny describes `webhook-id` as a way to detect duplicate deliveries. Record it with each action; the [webhook idempotency guide](/webhooks/guides/implement-webhook-idempotency) shows how.

## Conclusion

Webiny's webhooks connect your CMS to the services that build and serve your content. Remember that the secret is plain text you choose, not a `whsec_` key.

[Hookdeck Event Gateway](https://hookdeck.com) verifies Webiny's deliveries with your secret as typed, and retries and fans them out. [Start using Hookdeck for free](https://dashboard.hookdeck.com/signup).