Agent skill

Vern Webhooks Skill

Receive and verify Vern webhooks (Vern, the AI data-onboarding and spreadsheet-import platform, delivers workbook exports through Svix). Use when setting up Vern webhook handlers, debugging svix-signature verification, or handling workbook.production.export and workbook.preview.export batches in flat (1.0) or nested (2.0) format.

Install this skill

npx skills add hookdeck/webhook-skills --skill vern-webhooks


Vern is an AI data-onboarding platform. When a workbook is exported with the Webhook option, Vern POSTs the cleaned rows, in batches, to endpoints you register in an embedded Svix portal. Svix signs every delivery following Standard Webhooks, with svix-* header names: svix-id, svix-timestamp and svix-signature. One delivery is one batch of one export.

The body has no event name. workbook.production.export and workbook.preview.export deliver the same payload shape, and version is the export mode ("1.0" flat, "2.0" nested), not the event. No header carries the event type either, so register separate endpoints for preview and production (Vern's docs recommend this so test data never reaches your live database).

When to Use This Skill

  • How do I receive Vern webhooks?
  • How do I verify Vern webhook signatures (svix-signature)?
  • How do I handle workbook.production.export and workbook.preview.export deliveries?
  • How do I reassemble batches of a Vern workbook export (batch.id, batch.index)?
  • Why is my Vern webhook signature verification failing, or rejecting Hookdeck retries?

Verification (core)

Signed content is {svix-id}.{svix-timestamp}.{raw body}. Svix signs it with HMAC-SHA256 using the base64-decoded secret (the part after whsec_), base64-encodes the result, and sends one or more space-separated v1,<signature> entries. Use the official svix library, which compares in constant time. Read the svix-* headers, and when svix-id is absent fall back to the webhook-* headers (webhook-id, webhook-timestamp, webhook-signature).

import { Webhook } from 'svix'; // svix 2.x is ESM-only

const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.VERN_WEBHOOK_SECRET).verify(rawBody, {
  'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
  'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes
from svix.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["VERN_WEBHOOK_SECRET"])  # "whsec_..."
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
                     "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Each endpoint has its own signing secret, shown for the endpoint in the Svix portal that opens from Settings > Webhooks in Vern. Vern prints no example value; Svix endpoint secrets look like whsec_.... Keep the full value in VERN_WEBHOOK_SECRET. Handlers fail closed: with the variable unset (or not a whsec_ value) they return 500 instead of accepting anything. Vern's docs sample uses the svix library with wh.verify(req.body, req.headers); the version here adds the webhook-* fallback.

Hookdeck retries and replays hit the 5-minute window

The svix and standardwebhooks libraries always enforce a fixed 5-minute timestamp window, and it can't be configured. Hookdeck retries and replays resend the original svix-timestamp, so the library rejects any retry or replay that happens more than 5 minutes after the original delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in references/verification.md, where the window can be dropped or widened. Deduplicate on svix-id instead of relying on the timestamp.

Events and Payloads

Two events are documented (the list may not be exhaustive). Both deliver the same payload shapes, so the examples dispatch on version, not on an event name:

EventTriggered When
workbook.production.exportA production export from a workbook
workbook.preview.exportA staging/preview export from a workbook
versionModeBody
"1.0"Flat{version, workbook_id, external_id, batch, sheets}; sheets[].data[] are row objects (column keys, errors, row_index)
"2.0"Nested{version, workbook_id, company_name, external_id, export_mode, batch, root_sheets, data}; data is keyed by root sheet name, records carry children

Each delivery is one batch (flat: about 256 KB target, 512 KB ceiling; nested: up to 50 root records). Reassemble by grouping on batch.id, ordering by batch.index, and treating batch.index === batch.total - 1 as the last one. Batches can arrive in any order and retries can deliver one twice, so make the handler idempotent. See references/overview.md for the full payload reference.

Environment Variables

# Signing secret of the webhook endpoint in the Svix portal (starts with whsec_)
VERN_WEBHOOK_SECRET=whsec_xxxxx

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 vern --path /webhooks/vern

Add the tunnel URL as an endpoint in the Svix portal (Settings > Webhooks in Vern), subscribe it to one or both events, then export a workbook with the Webhook option. Svix Play gives you a throwaway URL for checking that an export fires before your real endpoint is wired up.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →