Agent skill
Webiny Webhooks Skill
Receive and verify Webiny webhooks (webiny.com, the open-source serverless headless CMS, Webiny 6.x). Use when setting up a Webiny webhook endpoint, configuring the signing secret, debugging webhook-id / webhook-timestamp / webhook-signature Standard Webhooks verification, or handling the {id, event, timestamp, webhookId, deliveryId, tenant, data} envelope that Webiny sends for CMS and other app events.
Install this skill
npx skills add hookdeck/webhook-skills --skill webiny-webhooks
Webiny 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-signatureverification fail with thestandardwebhooksorsvixlibrary? - 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):
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_ and hmac.compare_digest on bytes. No timestamp window is enforced by default, because retries and replays resend the original timestamp. Set WEBINY_ to opt in.
For complete handlers with tests, see examples/express/, examples/nextjs/, 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
{ "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.
Delivery Semantics
- The sender waits up to 10 minutes. Network errors,
429and5xxare 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 a4xxis not retried. - Deliveries can be resent from the admin. Dedupe on
webhook-id. - Respond
2xxquickly and process asynchronously.
Environment Variables
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
# 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 - Envelope, event vocabulary, delivery and retries
- references/setup.md - Creating a webhook, per-webhook vs global secret
- references/verification.md - Key derivation, manual verification, gotchas, debugging