Guide to Vern Webhooks: Features and Best Practices
Vern is an AI data-onboarding platform: it imports spreadsheet data into workbooks and cleans it before it reaches your product. Webhooks are how that cleaned data reaches you. When someone exports a workbook with the Webhook option, Vern posts the rows to your endpoint, split into batches if the export is large.
| Aspect | Value |
|---|---|
| Method | POST, JSON body, one batch per delivery |
| Signature headers | svix-id, svix-timestamp, svix-signature (Standard Webhooks) |
| Success | Any 2xx; non-2xx is retried by Svix on a backoff schedule |
| Delivery | At-least-once; svix-id is stable across retries |
| Challenge | None |
What are Vern webhooks?
Vern's webhooks carry data, not notifications: each delivery holds cleaned rows from a workbook export, ready to load into your database. Svix delivers and signs them, and you manage endpoints in a Svix portal embedded in Vern's settings. The portal also shows every delivery and its payload, lets you replay failures, and holds each endpoint's signing secret. Vern's webhook documentation is a single page.
Vern webhook features
| Feature | Details |
|---|---|
| Configuration | Settings > Webhooks, an embedded Svix portal |
| Signature | Standard Webhooks HMAC-SHA256, via Svix |
| Signature header | svix-signature (Svix default; Vern doesn't name it) |
| Secret | Per endpoint, in the portal. Format not shown |
| Body | JSON, one batch per delivery |
| Event name in body | None |
| Retries | Svix backoff schedule, manual replay in the portal |
| Source IPs | Not published |
Events and payloads
Vern documents two events:
| Event | When it fires |
|---|---|
workbook.production.export | A production export from a workbook |
workbook.preview.export | A staging/preview export from a workbook |
Both deliver the same payload, and nothing in it says which event it was. Vern recommends separate endpoints for preview and production so test data never reaches your live database, and that separation is also the only way to tell them apart.
The version field gives the shape, which follows the mode chosen in the export dialog:
1.0, flat: asheetsarray, one entry per sheet withid,name,row_count,start_row_index,end_row_indexanddata. Each row has your column keys plus anerrorsarray and arow_index.2.0, nested: child sheets are nested under their parents according to link rules. The body addscompany_name,export_mode(nested) androot_sheets, anddatais keyed by root sheet name. Every record has achildrenobject keyed by child sheet name. Circular link rules are treated as references, so there's no infinite recursion.
Both versions include workbook_id and external_id, the value you passed when you created the customer's company in Vern, or null.
Batches
Large exports are split, and each delivery is one batch:
| Field | Meaning |
|---|---|
batch.id | Shared by every batch of one export |
batch.index | 0-based position of this batch |
batch.total | Number of batches in the export |
batch.size | Records in this batch |
batch.timestamp | ISO 8601 creation time |
Flat exports are split by size, aiming at 256 KB with a 512 KB ceiling, so one sheet can span several batches. Nested exports carry up to 50 root records per batch, and a root always arrives with all its descendants. To rebuild an export, group by batch.id, sort by batch.index, and concatenate the data arrays; the batch with index equal to total - 1 is the last.
Vern's examples elide batch.id (batch_a1b2c3d4e5f6...), so no sample payload is reproduced here.
Setting up Vern webhooks
- In Vern, go to Settings > Webhooks. This opens the Svix portal.
- Click Add endpoint and enter your URL, such as
https://example.com/webhooks/vern. - Subscribe to
workbook.production.export, or toworkbook.preview.exporton a second endpoint such ashttps://example.com/webhooks/vern-preview. - Save, then open the endpoint and copy its signing secret into
VERN_WEBHOOK_SECRET. Vern doesn't show the format, but Svix secrets start withwhsec_; keep the prefix.
The next export run with the Webhook option goes to the matching endpoint. There's no verification challenge.
Before your own endpoint exists, the portal's Svix Play gives you a temporary URL that displays payloads in a web page. To route Vern through Hookdeck instead, create a source with the Vern type for each endpoint, paste that endpoint's secret, and register the source URL. For local testing, forward the source with the Hookdeck CLI:
npx hookdeck-cli listen 3000 vern --path /webhooks/vern
Securing Vern webhooks
Vern's verification example uses the svix library's Webhook.verify. Underneath, Svix signs svix-id, a dot, svix-timestamp, another dot and the raw body with HMAC-SHA256, keyed with the base64-decoded secret after whsec_, and sends one or more v1, entries in svix-signature. The function below does the same check by hand and also accepts webhook-* 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['svix-id'] ? 'svix' : 'webhook';
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 = decodeBase64(secret.replace(/^whsec_/, ''));
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);
});
}
The svix library in Vern's example also rejects timestamps more than five minutes old. Hookdeck applies no tolerance and keeps the original svix-timestamp when it retries or replays, so behind Hookdeck that library would reject real batches. The function above leaves the age check out.
The receiver stores each batch under svix-id, which stays the same across retries, and a worker assembles complete exports:
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;
}
}
// importBatches.save(messageId, batch) stores one batch once and resolves when durable.
function createVernReceiver(importBatches) {
const app = express();
app.post('/webhooks/vern', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.VERN_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const payload = parseJsonObject(req.body);
if (!payload) return res.sendStatus(400); // signed, but not a JSON object
const messageId = req.headers['svix-id'] || req.headers['webhook-id'];
try {
// A worker groups saved batches by payload.batch.id and loads the export once all batch.total have arrived.
await importBatches.save(messageId, payload);
} catch {
return res.sendStatus(503);
}
return res.sendStatus(200);
});
return app;
}
Run a second instance on /webhooks/vern-preview with the preview endpoint's secret.
When Vern posts to a Hookdeck source, a bad signature still gets 200, and the request is logged as failed verification and kept from your service.
Make Vern webhooks production-ready. Hookdeck Event Gateway verifies every export batch, keeps the full payload, and retries your loader until each batch lands.
Vern webhook limitations and pain points
Payloads don't say preview or production
The Problem: Preview data ends up in your production database.
Why It Happens: Both events send the same body with no event name, and Vern documents no header that carries one.
Workarounds:
- Give preview and production their own endpoints, URLs and secrets, and never subscribe one endpoint to both.
How Hookdeck Can Help: Use one Hookdeck source per Vern endpoint and connect each to a different destination, so preview and production never share a path.
Exports arrive in pieces
The Problem: Your loader sees half an import.
Why It Happens: Large exports are split into batches, one per delivery, and Vern doesn't say they arrive in order. Retries can deliver the same batch twice.
Workarounds:
- Store every batch, deduplicate on
svix-id, and only load an export once allbatch.totalbatches for itsbatch.idare present.
How Hookdeck Can Help: Hookdeck keeps each batch and retries any that your service fails to accept, so a gap in an export is visible and recoverable.
Retry schedule not stated
The Problem: You can't tell how long a failed batch will be retried.
Why It Happens: Vern says only that Svix retries non-2xx responses on a backoff schedule. Failed deliveries can be replayed by hand in the portal.
Workarounds:
- Return
200as soon as the batch is stored, and check the portal for failed deliveries after any outage.
How Hookdeck Can Help: Hookdeck takes each batch as soon as Svix sends it and retries your service on a schedule you choose.
Headers and secret format are left to Svix
The Problem: Vern's page doesn't name the headers or show what a secret looks like.
Why It Happens: Vern relies on the svix library and its portal. The svix-* names and the whsec_ prefix are Svix's defaults, not stated by Vern.
Workarounds:
- Check the secret in the portal before configuring a manual verifier, and inspect the headers of the first real delivery.
How Hookdeck Can Help: Hookdeck's Vern source accepts both svix-* and webhook-* headers and logs each verification result.
Best practices
Match external_id to your customer
Vern suggests matching external_id back to your customer record as soon as a batch arrives. Set it when you create each company in Vern.
Keep rows with errors visible
Each row has an errors array, such as "Email domain not allowed". Decide whether to import, quarantine or reject those rows rather than dropping them silently.
Keep the raw payload until loaded
Vern advises storing the raw payload until you've fully processed it. With batched exports, that's also what lets you rebuild an import after a failed load. Hookdeck's guide to webhook idempotency covers the deduplication side.
Conclusion
Vern's webhooks deliver cleaned customer data to your product in batches. Separate preview from production by endpoint, since the payload can't tell you which it is.
Hookdeck Event Gateway keeps every Vern batch and retries your loader until it succeeds. Create a Hookdeck account.