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.

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 verifyWebhookSignature utility:

1
import { verifyWebhookSignature } from "my-api";
2
3
// In your webhook handler
4
app.post("/webhooks", (req, res) => {
5
  // Verify the signature using your webhook secret
6
  const payload = verifyWebhookSignature(req, {
7
    secret: process.env.WEBHOOK_SECRET,
8
  });
9
10
  // Process the verified payload
11
  console.log("Received event:", payload);
12
13
  res.status(200).send("OK");
14
});

Setting up webhook signature verification

Configure signature verification in your API definition. Settings can be applied at the document level (inherited by all webhooks) or per-webhook (overrides document-level settings).

1
x-fern-webhook-signature:
2
  type: hmac
3
  header: x-webhook-signature
4
  algorithm: sha256
5
  encoding: hex
6
  payload-format:
7
    components: [timestamp, body]
8
    delimiter: "."
9
  timestamp:
10
    header: x-webhook-timestamp
11
    format: unix-seconds
12
    tolerance: 300

For full configuration details, see Webhook signature verification in OpenAPI.