Webhook signature verification

When you define webhooks in your API spec, Fern automatically generates utilities that allow your SDK users to verify webhook signatures and ensure events originate from your API. These helpers are generated for the TypeScript, Python, Java, Go, PHP, Ruby, and C# SDKs.

Fern supports two signature verification methods:

• Hash-based Message Authentication Code (HMAC) — Symmetric key verification using shared secrets
• Asymmetric — Public key verification using RSA, Elliptic Curve Digital Signature Algorithm (ECDSA), or Ed25519 keys

Generated SDK behavior

The generated SDK exposes a WebhooksHelper class with a static verifySignature method that returns whether the request is authentic. It takes the raw request body, the signature header value, the signing key (a shared secret for HMAC, a public key for asymmetric verification), and one parameter per additional payload component. A webhook that overrides the document-level configuration gets its own helper, such as PlantShippedWebhooksHelper.

These examples verify an HMAC signature over a timestamp and body:

import { WebhooksHelper } from "my-api";
const isValid = await WebhooksHelper.verifySignature(
  requestBody,
  signatureHeader,
  process.env.WEBHOOK_SECRET,
  timestampHeader,
);

Setting up webhook signature verification

Configure signature verification in your API definition with the x-fern-webhook-signature extension, at the document level (inherited by all webhooks) or per-webhook.