# Guide to Vern Webhooks: Features and Best Practices

[Vern](https://vern.so) 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](https://docs.vern.so/help-center/send/webhooks) 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:** 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:

| 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

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](/docs/cli):

```bash
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:

```javascript
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:

```javascript
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](/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](/docs/destinations), 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](/docs/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](/webhooks/guides/implement-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](https://hookdeck.com) keeps every Vern batch and retries your loader until it succeeds. [Create a Hookdeck account](https://dashboard.hookdeck.com/signup).