Gareth Wilson Gareth Wilson

Guide to Webiny Webhooks: Features and Best Practices

Published


Webiny 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 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

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headerwebhook-signature
BodyJSON
Event routingBody 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 fromExample use
Headless CMS apps (entry lifecycle events)Rebuild a static site, purge a CDN, sync to search
Other installed appsWhatever 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:

FieldMeaning in the 6.5.0 source
idThe background task's ID, also sent as webhook-id
eventThe event name
timestampWhen the event was sent
webhookIdThe webhook configuration that matched
deliveryIdThe delivery record
tenantThe Webiny tenant
dataThe 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:
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 forwards it locally:

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:

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:

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 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 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 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 verifies Webiny's deliveries with your secret as typed, and retries and fans them out. Start using Hookdeck for free.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.