***

title: Webhook signature verification
description: >-
Configure webhook signature verification in your Fern-generated SDKs to
validate HMAC or asymmetric signatures, protect against replay attacks, and
ensure webhook authenticity.
----------------------------

For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see [https://buildwithfern.com/learn/llms.txt](https://buildwithfern.com/learn/llms.txt). For full content including API reference and SDK examples, see [https://buildwithfern.com/learn/llms-full.txt](https://buildwithfern.com/learn/llms-full.txt).

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

<Note>
  Webhook signature verification is currently supported for TypeScript SDK generation only.
</Note>

## Generated SDK behavior

The generated SDK exposes a `verifyWebhookSignature` utility:

```typescript
import { verifyWebhookSignature } from "my-api";

// In your webhook handler
app.post("/webhooks", (req, res) => {
  // Verify the signature using your webhook secret
  const payload = verifyWebhookSignature(req, {
    secret: process.env.WEBHOOK_SECRET,
  });

  // Process the verified payload
  console.log("Received event:", payload);

  res.status(200).send("OK");
});
```

## 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).

<Tabs>
  <Tab title="OpenAPI">
    ```yaml title="openapi.yml"
    x-fern-webhook-signature:
      type: hmac
      header: x-webhook-signature
      algorithm: sha256
      encoding: hex
      payload-format:
        components: [timestamp, body]
        delimiter: "."
      timestamp:
        header: x-webhook-timestamp
        format: unix-seconds
        tolerance: 300
    ```
  </Tab>

  <Tab title="Fern Definition">
    ```yaml title="api.yml"
    webhook-signature:
      type: hmac
      header: x-webhook-signature
      algorithm: sha256
      encoding: hex
      payload-format:
        components: [timestamp, body]
        delimiter: "."
      timestamp:
        header: x-webhook-timestamp
        format: unix-seconds
        tolerance: 300
    ```
  </Tab>
</Tabs>

For full configuration details, see the docs for your API definition format:

<CardGroup cols={2}>
  <Card title="OpenAPI" href="/learn/api-definitions/openapi/endpoints/webhooks#signature-verification">
    Set up the `x-fern-webhook-signature` extension with full field reference and override examples
  </Card>

  <Card title="Fern Definition" href="/learn/api-definitions/ferndef/webhooks#signature-verification">
    Set up the `webhook-signature` block with full field reference and override examples
  </Card>
</CardGroup>