Gareth Wilson Gareth Wilson

Guide to Vern Webhooks: Features and Best Practices

Published


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.

AspectValue
MethodPOST, JSON body, one batch per delivery
Signature headerssvix-id, svix-timestamp, svix-signature (Standard Webhooks)
SuccessAny 2xx; non-2xx is retried by Svix on a backoff schedule
DeliveryAt-least-once; svix-id is stable across retries
ChallengeNone

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

FeatureDetails
ConfigurationSettings > Webhooks, an embedded Svix portal
SignatureStandard Webhooks HMAC-SHA256, via Svix
Signature headersvix-signature (Svix default; Vern doesn't name it)
SecretPer endpoint, in the portal. Format not shown
BodyJSON, one batch per delivery
Event name in bodyNone
RetriesSvix backoff schedule, manual replay in the portal
Source IPsNot published

Events and payloads

Vern documents two events:

EventWhen it fires
workbook.production.exportA production export from a workbook
workbook.preview.exportA 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: a sheets array, one entry per sheet with id, name, row_count, start_row_index, end_row_index and data. Each row has your column keys plus an errors array and a row_index.
  • 2.0, nested: child sheets are nested under their parents according to link rules. The body adds company_name, export_mode (nested) and root_sheets, and data is keyed by root sheet name. Every record has a children object 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:

FieldMeaning
batch.idShared by every batch of one export
batch.index0-based position of this batch
batch.totalNumber of batches in the export
batch.sizeRecords in this batch
batch.timestampISO 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

  1. In Vern, go to Settings > Webhooks. This opens the Svix portal.
  2. Click Add endpoint and enter your URL, such as https://example.com/webhooks/vern.
  3. Subscribe to workbook.production.export, or to workbook.preview.export on a second endpoint such as https://example.com/webhooks/vern-preview.
  4. Save, then open the endpoint and copy its signing secret into VERN_WEBHOOK_SECRET. Vern doesn't show the format, but Svix secrets start with whsec_; 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 all batch.total batches for its batch.id are 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 200 as 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.