Webhook signature verification
This feature is available only for the Enterprise plan. To get started, reach out to support@buildwithfern.com.
When you define a webhook signing scheme, in your API spec or API-wide in sdk-config.yml, 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, C#, and Rust SDKs. The Rust SDK supports HMAC verification configured in the API spec only; it doesn’t read the API-wide scheme.
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:
TypeScript
Python
Java
Go
PHP
Ruby
C#
Rust
Verify a request with a per-request algorithm
Some providers send the HMAC algorithm, and optionally a key ID, in a separate header on each request instead of signing with one fixed algorithm. When the signing scheme configures algorithm-header, WebhooksHelper also exposes a request-level helper that reads that header. Nothing changes for schemes without algorithm-header.
The helper takes the request headers, the raw request body, one parameter per additional payload component, and the signing key. Header lookup is case-insensitive. The helper reads the signature header and the algorithm header, splits the algorithm header on the configured key-id-delimiter, and maps the remaining value to an HMAC algorithm through algorithms. For key/value settings headers such as key=<id>,algorithm=HMAC_SHA256, setting key-id-parameter and algorithm-parameter makes the helper read the key ID and algorithm from those named parameters instead. When the algorithm header is absent, it falls back to the configured algorithm with no key ID. It then delegates to verifySignature, and returns false when the signature header is missing, the algorithm value isn’t listed in algorithms, or no signing key resolves.
The signing key is either the secret itself or a resolver callback that receives the key ID from the algorithm header and returns the matching secret, so the SDK never holds a key store. In Go, the key is always a resolver of type func(keyID string) (string, error), which receives an empty key ID when the header is absent. Java provides overloads for a String key and a Function<String, String> resolver.
These examples verify a request signed over the notification URL and body, resolving the secret from the key ID:
TypeScript
Python
Go
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.
Configure API-wide in sdk-config.yml
If every webhook your API sends is signed the same way, declare the scheme once under api.webhookSignature in sdk-config.yml instead of in the API definition. Every generator in the API emits the shared WebhooksHelper from this scheme, even when the spec models no webhooks and carries no x-fern-webhook-signature extension. This fits providers such as Twilio, which signs every webhook identically but doesn’t model incoming webhooks in its OpenAPI specs.
The block accepts the same configuration options as a webhook signature block in the API definition, including algorithm-header for providers that select the HMAC algorithm per request:
When the API definition also configures signatures, the more specific scheme wins: a webhook’s own signature overrides a document-level webhook-signature or x-fern-webhook-signature, which overrides api.webhookSignature in sdk-config.yml. A webhook with a distinct scheme still gets its own helper, such as PlantShippedWebhooksHelper; the API-wide scheme always backs the default WebhooksHelper.