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-signature verification fail with the standardwebhooks or svix library?
  • How do I handle the Webiny webhook envelope and dedupe retries?

Verification (core)

HeaderValue
webhook-idMessage ID (the background task ID), the same on every retry
webhook-timestampUnix seconds
webhook-signatureOne 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_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/, 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, 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

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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →