Farm.js

Webhooks

@farm.js/webhooks checks that a webhook really came from its sender, and signs the webhooks you send to your own users. It speaks Standard Webhooks, which Svix-based senders such as Clerk, Resend and Autumn use, and GitHub's scheme. Any other scheme plugs in as a plain object.

pnpm add @farm.js/webhooks

It uses only Web Crypto and the Fetch API, no Node modules, so the same code works in any runtime that has them. It is tested on Node and Bun.

Receive a webhook

// src/app/api/hooks/billing/route.ts
import { verifyWebhook, WebhookVerificationError } from "@farm.js/webhooks";

export async function POST(request: Request) {
  try {
    const event = await verifyWebhook(request, { secret: process.env.BILLING_WEBHOOK_SECRET! });
    await recordEvent(event.id, event.type, event.payload);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return Response.json({ error: error.code }, { status: 400 });
    }
    throw error;
  }
}

verifyWebhook reads the raw body, checks the signature against secret, refuses a timestamp more than 5 minutes from now, and parses the JSON body. Nothing reaches your code unverified.

The event has:

FieldMeaning
idThe sender's message id. The same message can arrive twice: dedupe on it
typeThe event type, from the scheme's headers or the payload's type field
timestampWhen the sender signed it, as a Date, for schemes that sign a timestamp
payloadThe parsed body, validated by schema when one is given
bodyThe raw body, exactly as signed

When something else already read the request, pass the raw body and headers instead: verifyWebhook({ body, headers }, options). The body must be the exact bytes the sender signed, not JSON you re-serialized.

Type the payload

Pass any Standard Schema validator, such as Zod, Valibot or ArkType:

import { z } from "zod";

const InvoicePaid = z.object({
  type: z.literal("invoice.paid"),
  data: z.object({ id: z.string(), amountCents: z.number() }),
});

const event = await verifyWebhook(request, { secret, schema: InvoicePaid });
event.payload.data.amountCents; // number

A body that doesn't match fails with INVALID_PAYLOAD, and error.issues lists why.

GitHub

import { github, verifyWebhook } from "@farm.js/webhooks";

const event = await verifyWebhook(request, {
  secret: process.env.GITHUB_WEBHOOK_SECRET!,
  scheme: github(),
});
event.type; // "pull_request", from `x-github-event`

GitHub signs no timestamp, so a replayed delivery passes the signature check. Dedupe on event.id (x-github-delivery). Set the webhook's content type to application/json.

Another sender

A scheme is an object with a name and a verify function that throws unless the signature is valid:

import { verifyWebhook, WebhookVerificationError, type WebhookScheme } from "@farm.js/webhooks";

const sharedToken: WebhookScheme = {
  name: "shared-token",
  async verify({ headers, secrets }) {
    if (!secrets.includes(headers.get("x-token") ?? "")) {
      throw new WebhookVerificationError("INVALID_SIGNATURE", "Wrong token.");
    }
    return { id: headers.get("x-request-id") ?? crypto.randomUUID() };
  },
};

Send a webhook

signWebhook returns Standard Webhooks headers for a body. Your users verify it with any Standard Webhooks library, or with verifyWebhook.

import { safeFetch } from "@farm.js/core/safe-fetch";
import { signWebhook } from "@farm.js/webhooks";

const body = JSON.stringify({ type: "invoice.paid", data: invoice });
const headers = await signWebhook({ secret: endpoint.secret, body, id: message.id });

await safeFetch(endpoint.url, {
  method: "POST",
  headers: { "content-type": "application/json", ...headers },
  body,
  redirect: "error",
  signal: AbortSignal.timeout(10_000),
});
  • Reuse the message id when you retry, so the receiver can drop the repeat.
  • Send to user-supplied URLs with safeFetch, so an endpoint can't point at your private network.

This package doesn't store endpoints, queue deliveries or retry them yet.

Secrets and rotation

A secret that starts with whsec_ is a Standard Webhooks secret: the rest is the base64 key. Any other string is used as its UTF-8 bytes, as Farm's Polar and Autumn integrations do.

To rotate, pass both secrets. verifyWebhook accepts a signature made with either, and signWebhook signs with both, so receivers on either secret keep working:

await verifyWebhook(request, {
  secret: [process.env.WEBHOOK_SECRET!, process.env.OLD_WEBHOOK_SECRET!],
});

An empty secret, such as an unset environment variable, fails with INVALID_SECRET instead of accepting everything.

Errors

WebhookVerificationError has a stable code. Answer with a 4xx status: senders retry a 5xx.

codeWhen
INVALID_SECRETsecret is empty, or a whsec_ secret isn't valid base64
MISSING_HEADERSA signature header is missing; the message names each one
INVALID_TIMESTAMPwebhook-timestamp isn't Unix seconds
TIMESTAMP_OUT_OF_RANGEThe timestamp is more than toleranceSeconds (default 300) from now
INVALID_SIGNATURENo signature matches any secret
INVALID_BODYThe signature is valid, but the body isn't JSON
INVALID_PAYLOADThe body doesn't match schema