Guide to Webiny Webhooks: Features and Best Practices
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
| 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:
- the webhook's own signing secret;
- the global signing secret in Webhook settings;
- 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:
- In the Webiny admin, open the webhooks settings and create a webhook.
- Enter the endpoint URL, for example
https://your-app.com/webhooks/webiny. - Choose events from the list the admin shows.
- Enter a signing secret, or leave it empty to use the global one.
- 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.