Webhooks
A webhook helper is the SDK method a receiving server calls when your API delivers an event. It checks the delivery's signature against your signing secret, then decodes the body into a typed event, so the people integrating with your API do not have to rebuild your signature scheme or hand-write a type for every event.
Webhook helpers are declared, not inferred. The OpenAPI document's top-level webhooks describe the events, and a webhookUnwrap method in your configuration decides where the helper lives, which events it decodes, and how it verifies them. A configuration with no webhookUnwrap method generates nothing from the document's webhooks: no helper, no event types, no verifier. The one place the generator writes such a method for you is the starter configuration it creates for a document that has none; see Starter configuration. The configuration reference at the end lists every key a helper takes.
Start here
Say your API signs each delivery with Standard Webhooks and declares two events at the top of its OpenAPI document, each payload carrying a type property that names its event and the widget it concerns:
webhooks:
widget.created:
post:
requestBody:
content:
application/json:
schema: { $ref: '#/components/schemas/WidgetCreatedEvent' }
widget.deleted:
post:
requestBody:
content:
application/json:
schema: { $ref: '#/components/schemas/WidgetDeletedEvent' }
Declare a client option to hold the signing secret, and a webhookUnwrap method that reads it:
{
"clientSettings": {
"opts": {
"webhook_secret": {
"type": "string",
"nullable": true,
"readEnv": "ACME_WEBHOOK_SECRET"
}
}
},
"resources": {
"webhooks": {
"methods": {
"parse": {
"kind": "webhookUnwrap",
"webhook": {
"eventTypes": {
"widget.created": "widget.created",
"widget.deleted": "widget.deleted"
},
"webhookKeyOpt": "webhook_secret"
}
}
}
}
}
}
That is the whole change. The client reads the secret from ACME_WEBHOOK_SECRET, or from the option you pass when constructing it (see The signing secret for each target), and the parse method verifies every delivery before decoding it:
// `body` is the raw request body as a string; `headers` are the request's headers.
const event = client.webhooks.parse(body, { headers });
switch (event.type) {
case 'widget.created':
console.log(event.widget.id);
break;
case 'widget.deleted':
break;
}
// Or check the signature alone, or decode a body you verified elsewhere.
client.webhooks.verifySignature(body, headers);
const unchecked = client.webhooks.parseUnsafe(body);
# `payload` is the raw request body; `headers` are the request's headers.
event = client.webhooks.parse(payload, headers=headers)
if event.type == "widget.created":
print(event.widget.id)
# Or check the signature alone, or decode a body you verified elsewhere.
client.webhooks.verify_signature(payload, headers)
unchecked = client.webhooks.parse_unsafe(payload)
Verification runs in the SDK itself, with the standard library alone. The async client has the same methods.
payload, err := io.ReadAll(r.Body)
if err != nil {
return err
}
event, err := client.Webhooks.Parse(payload, r.Header)
if err != nil {
return err // the signature did not verify, or the body did not decode
}
switch e := event.AsUnion().(type) {
case acme.WidgetCreatedWebhookEvent:
fmt.Println(e.Widget.ID)
case acme.WidgetDeletedWebhookEvent:
}
// Or check the signature alone, against an explicit secret and clock.
err = client.Webhooks.VerifySignature(payload, r.Header, secret, time.Now())
# `payload` is the raw request body; `headers` is a Hash of the request's headers.
event = client.webhooks.parse(payload, headers: headers)
case event
when Acme::Models::WidgetCreatedWebhookEvent
puts event.widget.id
end
# `verify_signature` returns the verified payload as a Hash with symbol keys.
data = client.webhooks.verify_signature(payload: payload, headers: headers)
unchecked = client.webhooks.parse_unsafe(payload)
// `headers` is the SDK's `Headers` type, built from the request's headers.
val event = client.webhooks().parse(body, headers, null) // null: use the client's secret
if (event.isWidgetCreated()) {
println(event.asWidgetCreated().widget().id())
}
client.webhooks().verifySignature(body, headers, null)
val unchecked = client.webhooks().parseUnsafe(body)
// `headers` is the SDK's `Headers` type, built from the request's headers.
var event = client.webhooks().parse(body, headers, null); // null: use the client's secret
if (event.isWidgetCreated()) {
System.out.println(event.asWidgetCreated().widget().id());
}
client.webhooks().verifySignature(body, headers, null);
var unchecked = client.webhooks().parseUnsafe(body);
// `$body` is the raw request body; `$headers` is an array of the request's headers.
$event = $client->webhooks->parse($body, $headers);
if ($event instanceof \Acme\Webhooks\WidgetCreatedWebhookEvent) {
echo $event->widget->id;
}
$client->webhooks->verifySignature($body, $headers);
$unchecked = $client->webhooks->parseUnsafe($body);
use acme::{webhooks, WebhookEvent};
// `body` is the raw request body; `headers` is its `http::HeaderMap`.
// Rust reads no client option for the secret, so pass it on every call.
webhooks::verify_signature(&body, &headers, &secret)?;
// `event_type` names the event: the enum is told apart from outside the payload.
match WebhookEvent::parse(event_type, &body)? {
WebhookEvent::WidgetCreated(created) => println!("{}", created.widget.id),
_ => {}
}
// `body` is the request body as received (`Data`); `headers` is a `[String: String]`.
let event = try await client.webhooks.parse(body, headers: headers)
switch event {
case .widgetCreated(let created):
print(created.widget.id)
case .widgetDeleted, .undocumented:
break
}
try await client.webhooks.verifySignature(body, headers: headers)
let unchecked = try client.webhooks.parseUnsafe(body)
// `body` is the raw request body as a String; `headers` is a Map of the request's headers.
final event = client.webhooks.parse(body, headers: headers);
if (event is ParseWebhookEventWidgetCreated) {
print(event.value.widget.id);
}
// `body` is the raw request body; copy every request header into `headers`.
acme::Headers headers;
for (const auto &field : request.headers) {
headers.add(field.name, field.value);
}
auto event = client.webhooks().parse(body, headers);
if (const auto *created = event.widget_created()) {
std::cout << created->widget.id << '\n';
}
// Or decode a body you verified elsewhere.
auto unchecked = client.webhooks().parse_unverified(body);
Pass the body exactly as it arrived, before any JSON parsing. The signature covers the raw bytes, so a body that was parsed and re-serialized fails verification even when it holds the same data.
Declaring a helper
A webhook helper is a method with "kind": "webhookUnwrap" and a webhook block. It is placed like any other method, and the method key is its name in every target, cased for each language: resources.webhooks.methods.parse generates client.webhooks.parse. A top-level helper on a resource with another name, such as resources.events.methods.unwrap, follows that path in Ruby, Java, Kotlin, PHP, Swift, Dart and C++ (client.events), while TypeScript, Python and Go still generate it at client.webhooks. Rust has no webhook method on the client: its helper is a set of free functions in the crate's webhooks module.
Go and Ruby also keep a Parsed (Go) or parsed (Ruby) alias beside a top-level parse method of any other name, which calls it with the same arguments; Ruby marks it deprecated.
eventTypes
eventTypes lists the events the helper decodes. Each key is an event's name as the generator derives it: the webhook operation's operationId when it has one, otherwise the webhook's key under webhooks. Only the keys select events; the value is descriptive, and repeating the event name, as above, is the convention.
| Value | Effect |
|---|---|
| A map of event names | The helper decodes those events. Its return type is a union over them. |
{} |
The helper decodes every webhook the document declares. |
| A map that matches no event | When no helper in the configuration matches any event, some targets decode every webhook instead of shipping the helper with nothing to decode, while others generate nothing for it (PHP generates no webhook service). Use {} to decode every webhook in every target. Otherwise the key selects no event, and what a target generates for a helper left with none varies. Each key that names no event is reported with Config/WebhookUnknownEventType. |
When two helpers could claim the same event, one that lists the event explicitly wins over one with an empty map, whatever their order in the configuration. A webhook that no helper claims gets no generated type, except in Rust, whose event enum has an arm for every top-level webhook once the configuration has any helper.
Operation callbacks are not part of the event set; only the document's top-level webhooks are.
Scoped helpers
A helper does not have to sit on a top-level webhooks resource. Nest it under any resource and it is generated there, so one API can ship a helper per product area:
{
"resources": {
"notifications": {
"subresources": {
"webhooks": {
"methods": {
"parse_alert": {
"kind": "webhookUnwrap",
"webhook": {
"eventTypes": { "alert.created": "alert.created", "alert.resolved": "alert.resolved" },
"webhookKeyOpt": "webhook_secret"
}
}
}
}
}
}
}
}
That generates client.notifications.webhooks.parseAlert(...) in TypeScript, client.notifications.webhooks.parse_alert(...) in Python, and client.Notifications.Webhooks.ParseAlert(...) in Go. A segment that names no resource your configuration generates gets a container generated for it. In Go, a path that names a resource your configuration already generates puts the helper beside that resource's methods; in TypeScript, and in Python unless the helper's leaf is itself a generated webhooks resource, such a helper is generated on client.webhooks instead, and the top-level webhooks module verifies it (see Signature settings). Each scoped helper carries its own event set, signing secret, signature settings and companions. Rust is the exception: it generates one webhooks module for the crate, whose event enum and companions follow the top-level helper's settings (a scoped one's when there is no top-level helper), and whose event enum decodes every top-level webhook the document declares, whatever each helper's eventTypes selects. Signature settings stay per helper: when every helper signs the same way, the module's verify_signature checks all of them, and when they differ, verify_signature checks only the top-level helper's deliveries and every other helper gets a module of its own, such as webhooks::parse_alert::verify_signature (see Signature settings).
The signing secret
webhookKeyOpt names the clientSettings.opts entry the helper reads its secret from. Declare that option yourself, with a readEnv, so you choose the environment variable callers set. Naming it webhook_secret, as above, gives it the same name on every client: TypeScript always reads the secret from a webhookSecret option, and takes only the readEnv of a declared option of that name.
| Target | Set on the client | Read from |
|---|---|---|
| TypeScript | new Acme({ webhookSecret }) |
ACME_WEBHOOK_SECRET |
| Python | Acme(webhook_secret=...) |
ACME_WEBHOOK_SECRET |
| Go | option.WithWebhookSecret(...) |
ACME_WEBHOOK_SECRET |
| Ruby | Acme::Client.new(webhook_secret: ...) |
ACME_WEBHOOK_SECRET |
| Java, Kotlin | .webhookSecret(...) on the client builder |
ACME_WEBHOOK_SECRET (or the acme.webhookSecret system property), when the client is built with fromEnv() |
| PHP | new Client(webhookSecret: ...) |
ACME_WEBHOOK_SECRET |
| Swift | AcmeClient(webhookSecret: ...), or Configuration.webhookSecret |
ACME_WEBHOOK_SECRET, on macOS and Linux |
| Dart | AcmeClient(webhookSecret: ...) |
ACME_WEBHOOK_SECRET, when the client is built with AcmeClient.fromEnvironment() |
| C++ | ClientOptions::webhook_secret |
ACME_WEBHOOK_SECRET, when the option is unset |
Ruby resolves the secret each time a verifying method is called: a secret passed to the constructor wins, then the environment variable as it is at call time, then the value the client read when it was built, so a secret rotated in the environment takes effect without a new client. Rust reads no client option at all; its verifying functions take the secret as an argument. C# generates no helper that would read it, so it declares no client setting for the option a helper's webhookKeyOpt names, unless the config also sends that option with requests or a signed URL signs with it (see What gets generated).
Leave webhookKeyOpt unset and the helper still verifies. TypeScript, Python, Go, Ruby, PHP, Swift, Dart and C++ add a webhook_secret option for it, whose environment variable is derived from the SDK name, and not every target derives it the same way. Java and Kotlin add none, and their helper reads no client option, not even a declared webhook_secret, so every call has to pass the secret. Naming a declared option is the way to get one option and one variable everywhere.
Every verifying method also takes the secret per call, which wins over the client's. That suits an API that issues a different secret per endpoint or per tenant.
Secrets use the Standard Webhooks format: an optional whsec_ prefix, then base64. A secret that decodes to nothing is refused rather than used, because an HMAC under an empty key is one anyone can compute.
bytesKey
bytesKey says how Python reads a per-call key passed as bytes. With raw, the default, the bytes are the HMAC key itself, as the Standard Webhooks library reads them. With utf8, the parse method decodes the bytes as UTF-8 and reads the text the way it reads a str key: an optional whsec_ prefix is stripped and the rest is base64-decoded. The verifying companions (verify_signature, unwrap) keep using bytes as the raw key.
{ "kind": "webhookUnwrap", "webhook": { "eventTypes": {}, "bytesKey": "utf8" } }
Set utf8 when your users hand over the secret your dashboard shows as bytes, for example read from a file or from os.environb. Only Python tells a bytes key from a string one, so the other targets ignore the setting. It is experimental.
Turning verification off
Set webhookKeyOpt to false for an API that does not sign its deliveries:
{
"kind": "webhookUnwrap",
"webhook": {
"eventTypes": {},
"webhookKeyOpt": false
}
}
The parse method then only decodes, ignoring any headers it is given, and loses the two companions that verify. It keeps its arguments, so call sites do not change; in TypeScript, Python, Ruby, PHP and Dart, passing it a secret throws rather than being silently ignored. Swift is the exception: its parse method still verifies, against a secret that every call then has to pass, because the configuration holds none, and it throws WebhookError with code missingSecret without one.
Nothing else turns verification off: a helper that leaves webhookKeyOpt unset verifies with the default settings below. Verification is a configuration decision, never a call-site one, so a verifying parse method in TypeScript, Python, Go, Ruby, Swift or C++ refuses a call without headers rather than skipping the check.
Some targets have a form of the parse method without headers, for replaying an event you stored after verifying it. On Java and Kotlin, parse(body) decodes without checking anything, and so does parse(UnwrapWebhookParams) without headers when neither the params nor the client hold a secret. On PHP and Dart, a parse call without headers decodes unchecked when no secret is available, and throws when one is. Pass the headers on every live delivery.
Signature settings
Verification follows the Standard Webhooks scheme: an HMAC over {id}.{timestamp}.{body}, a v1,-prefixed base64 signature (any of several space-separated signatures may match), and a timestamp checked against a replay window in both directions. These keys adjust it:
| Key | Default | What it is |
|---|---|---|
signatureAlgorithm |
hmac-sha256 |
One of hmac-sha1, hmac-sha256, hmac-sha512, ed25519, rsa-sha256. |
signatureHeader |
webhook-signature |
The header carrying the signature. |
timestampHeader |
derived | The header carrying the unix-seconds timestamp. |
toleranceSeconds |
300 |
How far the timestamp may be from the receiver's clock, in seconds. |
The message id and timestamp headers are derived from the signature header's prefix, so signatureHeader: "x-acme-signature" reads x-acme-id and x-acme-timestamp. A signature header that does not end in -signature or _signature keeps the default webhook-id and webhook-timestamp. timestampHeader overrides the derived timestamp header.
Not every target applies these settings yet:
| Target | Header names and window | Algorithms verified |
|---|---|---|
| TypeScript | As configured; helpers without a module of their own, such as those on the top-level webhooks resource, share one scheme |
hmac-sha256. With any other, every verifying method throws WebhookVerificationError naming the algorithm, so a receiver that catches refused deliveries catches it too, and the message names the decode-only parseUnsafe (under its configured name, if renamed) for a delivery you checked yourself. |
| Rust | As configured, per helper | hmac-sha256, hmac-sha512. With any other, that helper gets no verifier, and no other helper's verifier checks its deliveries. |
| Swift | As configured | hmac-sha256, hmac-sha512. With any other, the parse method always throws WebhookError with code unsupportedSignatureScheme, the verifying companions are not generated, and parseUnsafe decodes a delivery you checked yourself. |
| Python | As configured; helpers without a module of their own, such as those on the top-level webhooks resource or under a real resource, share one scheme |
hmac-sha1, hmac-sha256, hmac-sha512. With any other, the parse method, verify_signature and unwrap raise WebhookVerificationError naming the algorithm for every delivery, and parse_unsafe decodes a delivery you checked yourself. |
| Dart | As configured | hmac-sha1, hmac-sha256, hmac-sha512. With any other, a parse call with headers throws WebhookVerificationException, and headers: null decodes a delivery you checked yourself. |
| C++ | As configured | hmac-sha1, hmac-sha256, hmac-sha512. With any other, the helper is not generated and the build reports Unsupported/WebhookSignatureAlgorithm. |
| Go | As configured, per helper; helpers without a module of their own, such as those on the top-level webhooks resource, share one scheme |
hmac-sha1, hmac-sha256, hmac-sha512. With any other, the methods are still generated, and every verifying one returns an error that matches ErrNoMatchingSignature, names the algorithm as unsupported and points at ParseUnsafe, which decodes a delivery you checked yourself. |
| Ruby | As configured | hmac-sha1, hmac-sha256, hmac-sha512. With any other, the parse method and the verifying companions keep their signatures but always raise Errors::WebhookVerificationError naming the algorithm, and parse_unsafe decodes a delivery you checked yourself. |
| PHP | As configured, each helper with its own | hmac-sha1, hmac-sha256, hmac-sha512. With any other, the parse method throws WebhookException naming the algorithm whenever headers or a secret are available, verifySignature and unwrap always throw it, and parseUnsafe (or, when it is turned off, a parse call without headers on a client with no webhook secret) decodes a delivery you checked yourself. |
| Java, Kotlin | As configured, each helper with its own | hmac-sha1, hmac-sha256, hmac-sha512, with the JDK alone. With any other, every method is still generated and no secret is needed: every method that is given a delivery's headers throws the SDK's webhook exception, whose reason (its message in Kotlin, its cause in Java) names the algorithm as unsupported (verifySignature and unwrap given params without headers throw for the missing headers instead), and parseUnsafe (under its configured name, if renamed) decodes a delivery you checked yourself. |
If your API signs with anything other than HMAC-SHA256 under the default headers, check the targets you ship against this table. Generation reports every gap in it for the targets you generate: an algorithm a target cannot verify as Unsupported/WebhookSignatureAlgorithm, and header names or a window it ignores as Unsupported/WebhookSignatureSettings.
In Rust, helpers that sign differently are verified apart. The free webhooks::verify_signature and verify_signature_at, and unwrap when configured, keep checking the top-level helper's deliveries (none are generated when that helper uses an algorithm Rust cannot verify, or turns verification off while the remaining helpers still sign differently; an opted-out helper is not counted when comparing schemes). Each other helper gets a module named after its method, holding its verifier (named by its helpers.verifySignature), verify_signature_at, and an unwrap when its helpers.unwrap asks for one: parse_alert generates webhooks::parse_alert::verify_signature(payload, headers, secret). When an earlier helper's module, one of the file's own items (such as unwrap) or a reserved name already takes the method name, the module adds the helper's resource path (notifications_webhooks_parse_alert). When every helper signs the same way, there are no per-helper modules.
Refused deliveries
A delivery that fails verification, because a signed header is missing or malformed, its timestamp is outside the window, or no signature matches, is refused with an error a receiver can catch on its own:
| Target | A refused delivery | A missing or unusable secret |
|---|---|---|
| TypeScript | WebhookVerificationError, exported from the package root; it extends the SDK's base error (AcmeError) |
A plain Error. verifySignature and unwrap also throw a plain Error for a signed header they find missing before verifying. |
| Python | WebhookVerificationError, exported from the package root and a subclass of the SDK's base error. The parse method raises its subclass WebhookMissingHeadersError, which is also a ValueError, for a missing or empty signed header. verify_signature and unwrap raise a plain ValueError for a signed header they cannot find; an empty one in a dict or other mapping reaches the verifier and raises WebhookMissingHeadersError, as the parse method does. |
ValueError |
| Go | An error that matches exactly one of the root package's ErrRequiredHeaders, ErrInvalidHeaders, ErrNoMatchingSignature, ErrMessageTooOld and ErrMessageTooNew with errors.Is |
An error that matches none of them |
| Ruby | Acme::Errors::WebhookVerificationError, a subclass of Acme::Errors::Error |
ArgumentError |
| Java | AcmeWebhookException("Could not verify webhook event signature"), with the reason on its cause |
AcmeException when no secret is set, AcmeWebhookException when it is not valid. parse(UnwrapWebhookParams) with headers throws IllegalStateException when no secret is set and IllegalArgumentException when it is not valid. |
| Kotlin | AcmeWebhookException, with the reason as its message. Every method except parse(UnwrapWebhookParams) throws AcmeInvalidDataException naming a missing signed header; that one throws AcmeWebhookException. |
As Java |
| PHP | Acme\Core\Exceptions\WebhookException |
WebhookException |
| Rust | Error::Webhook(WebhookVerificationError), whose kind() is MissingHeader, InvalidHeader, InvalidSignature or OutsideTolerance |
Error::Config |
| Swift | WebhookError, whose code names the check: missingHeader, invalidHeader, timestampOutsideTolerance or signatureMismatch, so catch WebhookError.signatureMismatch matches one |
WebhookError with code missingSecret or invalidSecret |
| Dart | WebhookVerificationException, a subclass of AcmeException |
WebhookVerificationException |
| C++ | acme::WebhookVerificationError, a subclass of acme::Error |
acme::WebhookVerificationError |
Companion methods
Beside its parse method, a helper generates companion methods:
| Companion | Default | What it does |
|---|---|---|
verify_signature |
On | Checks the signature and throws when it does not verify. It returns nothing, except in Ruby, where it returns the verified payload as a Hash with symbol keys. |
parse_unsafe |
On | Decodes the body into the typed event without verifying it, for tests or a body you verified elsewhere. |
unwrap |
Off | Verifies the signature, then returns the decoded JSON untyped. |
The two verifying companions, verify_signature and unwrap, are generated only when the helper verifies; a helper with webhookKeyOpt: false gets parse_unsafe alone.
Dart and C++ generate no companions and ignore helpers. C++ instead always pairs each parse method with a decode-only <method>_unverified, and an SDK whose helper verifies ships acme::verify_webhook_signature(body, headers, options), which checks a signature on its own.
helpers switches them on or off, or renames them. Names are written in snake_case and re-cased for each target:
{
"kind": "webhookUnwrap",
"webhook": {
"eventTypes": {},
"webhookKeyOpt": "webhook_secret",
"helpers": {
"verifySignature": true,
"parseUnsafe": "parse_raw",
"unwrap": true
}
}
}
| Value | Effect |
|---|---|
true (the default) |
verify_signature and parse_unsafe. |
false |
The parse method alone. |
| An object | Each of verifySignature, parseUnsafe and unwrap is true (on, default name), false (off), or a string (on, under that name). |
A companion is left out when its name repeats the parse method's or another companion's. The starter configuration names its parse method unwrap, so an unwrap companion there needs a name of its own. parseUnsafe may never take a verifying companion's name (verify_signature, unwrap, or the name you gave either), because a caller trusting that name would accept unsigned deliveries; it is left out and reported as Config/WebhookHelperNameUnsafe. A companion that clashes with another method on the same generated class is resolved by each target's own naming rules, which can leave it out or qualify its name.
Rust keeps each helper's verify_signature function even with companions off, because it is the only verifier that helper has: the top-level helper's in webhooks, and, when helpers sign differently, each other helper's in its own module (see Signature settings). A helper signed with an algorithm Rust cannot verify has no verifier at all.
Naming
keyParam
keyParam names the per-call argument that overrides the client's secret, before target casing. It defaults to key:
{ "kind": "webhookUnwrap", "webhook": { "eventTypes": {}, "keyParam": "secret" } }
TypeScript (parse(body, { headers, secret })), Python (secret=) and Ruby (secret:) use it on the parse method and the verifying companions. Java, Kotlin, PHP, Swift and Dart already call the argument secret, and the other targets take the key positionally (Go's parse method through option.WithWebhookSecret), so they ignore it. The value must be a lowercase snake_case identifier that is not headers, body, payload, a keyword of a generated language, or a name the generated helpers already use.
typeName
typeName names the event union the parse method returns, before target casing:
{ "kind": "webhookUnwrap", "webhook": { "eventTypes": {}, "typeName": "ParsedWebhookEvent" } }
Without it, each target keeps its own default: some name the union after the method (parse_alert returns ParseAlertWebhookEvent), others name a top-level helper's union ParsedWebhookEvent whatever the method is called, and Rust's is WebhookEvent. Set it when you rename the parse method of an SDK you have already published, so the type your users import keeps its name.
The name must end in Event. One that a model, a webhook event's own type, another helper's union or a WebSocket event type already uses is ignored, with a Config/WebhookTypeNameConflict warning, and the helper keeps its default. Go always keeps its default names.
Event types
Each event gets its own type, named after the event with WebhookEvent appended: widget.created generates WidgetCreatedWebhookEvent. An event whose operationId already ends in Webhook, such as widgetCreatedWebhook, does not repeat the word. Rust names no type of its own for a payload that references a component schema: its event enum's arm holds that schema's model (WidgetCreatedEvent in the Start here example).
Other keys
| Key | What it is |
|---|---|
summary, description |
Doc text for the helper. Swift, Dart and C++ render it on the parse method, preferring summary when both are set; PHP renders it on the event union's class, preferring description. Either one also replaces the summary or description of every webhook the helper claims, so it becomes the doc text of those events' types in the targets that document them. |
discriminator |
The payload property that tells the events apart, such as type. Python, Java, Kotlin, Swift, Dart and C++ decode the union by it; without it they look for a property every payload pins to a distinct value, which all but Python try type for first. |
What gets generated
| Target | Parse method | Companions | Verifier |
|---|---|---|---|
| TypeScript | client.webhooks.parse(body, { headers, key? }) |
verifySignature(body, headers, key?), parseUnsafe(body), unwrap(body, headers, key?) |
Built in, no dependency |
| Python | client.webhooks.parse(payload, *, headers, key=None), sync and async |
verify_signature(payload, headers, *, key=None), parse_unsafe(payload), unwrap(...) |
Built in, standard library only; each helper checks its own hmac-sha1, hmac-sha256 or hmac-sha512 scheme |
| Go | client.Webhooks.Parse(payload, headers, opts...) |
VerifySignature(payload, headers, secret, now), ParseUnsafe(payload), Unwrap(payload, headers, opts...) |
Built in, standard library only |
| Java, Kotlin | parse(body, headers, secret), parse(UnwrapWebhookParams), and parse(body), which only decodes |
verifySignature(...), parseUnsafe(body), unwrap(...) returning JsonValue |
Built in, JDK only |
| Ruby | client.webhooks.parse(payload, headers:, key: nil), where nil resolves the client's secret |
verify_signature(payload:, headers:, key: nil), parse_unsafe(payload), unwrap(payload, headers:, key: nil) |
Built in, no gem |
| PHP | parse(string $body, ?array $headers = null, ?string $secret = null), which verifies whenever headers are passed or a secret is available |
verifySignature($body, $headers, $secret), parseUnsafe($body), unwrap(...) |
Built in, no dependency |
| Rust | <Union>::parse(event_type, payload), which only decodes |
Free functions in the webhooks module: verify_signature(payload, headers, secret), verify_signature_at(...), parse_unsafe(event_type, payload), unwrap(payload, headers, secret); the verifying three only for hmac-sha256 and hmac-sha512, and in a module per helper (webhooks::<helper>::verify_signature) when helpers sign differently |
hmac and sha2 crates, only when a verifier is generated |
| Swift | parse(_ payload: Data, headers:, secret:) async throws, and the same taking a String |
verifySignature(...), parseUnsafe(_:), unwrap(...) returning JSONValue |
Built in, no dependency |
| Dart | parse(String body, {required headers, secret}); headers: null decodes without checking only when no secret is available |
Not generated | package:crypto |
| C++ | parse(body, headers), parse(body, headers, secret), and parse_unverified(body), which only decodes |
Not generated | Built in |
| C# | Not generated: the webhook service is an empty accessor, and the README's "Known gaps" section says so | None | None |
Method names above follow the helper in the Start here example; yours follow your method key. The event types are generated on every target, C# included, so a C# receiver can deserialize a delivery into them after checking its signature itself. C# declares no WebhookSecret client setting for the signing key, since nothing in the SDK would read it, unless the config also sends that option with requests or a signed URL signs with it. The CLI target generates no command for a webhook helper.
In Rust, the parse method decodes by the event-type string you pass, because the union is told apart from outside the payload: call verify_signature first, then parse.
README
The generated README for TypeScript, Python, Go, Java, Kotlin, Ruby, Swift and C++ includes a ## Webhooks section when the SDK has a webhook helper the client reaches directly, such as client.webhooks. The PHP, Rust, Dart and C# READMEs have none; the C# README instead lists, under "Known gaps", the type each helper with events decodes into, and for a signed helper tells the reader to verify deliveries before deserializing them. A helper that only exists under another resource is documented where each target puts it on the client: TypeScript always also generates it at client.webhooks; Python does too, unless the SDK already has a webhooks resource somewhere else, in which case the helper stays under its parent and the section is left out; Ruby documents it at its own path (client.notifications.webhooks); and C++ lists every helper at its own path (client.notifications().webhooks()). Go, Java, Kotlin and Swift reach it only through its parent resource, so they leave it to the API reference.
Except in C++, the section opens with a short explanation that is the same in every target: pass the raw, unparsed request body together with the request headers, because the signature covers the body as it arrived. Then comes a snippet calling the parse method, where the signing secret comes from (the client option and its environment variable, or, on a Java or Kotlin SDK whose helper reads none, that each call passes it), and a bullet for each companion the helper generates. A helper with webhookKeyOpt: false gets an explanation that says it only decodes, and that deliveries must be checked some other way; in Swift, whose parse method still verifies, it says to pass secret on every call. In Go, Java, Kotlin, Python, Ruby and Swift, a helper signed with ed25519 or rsa-sha256 gets the decode-only explanation too, with a note naming the algorithm the SDK cannot verify and a snippet that decodes with the helper's parseUnsafe method when it has one (Swift leaves the section out when the helper has none). TypeScript shows the verifying call, which throws for such a helper. The C++ section is one paragraph covering every webhook method (verification, the client's secret and its environment variable, the error thrown, the decode-only twin), a snippet, and the union each method returns.
Starter configuration
When a build has no configuration and the document declares top-level webhooks, the starter configuration the generator writes includes a webhooks resource with one unwrap method whose eventTypes lists every event. It leaves webhookKeyOpt unset, so verification is on with the default settings, reading the secret from the option most targets add for it (Java, Kotlin and Rust take it per call; see The signing secret). Name the secret option yourself, as in Start here, before you publish.
If the document already has a path-derived webhooks resource, the starter puts the helper under a different key so both survive.
Importing a Fern project
A Fern project's webhook settings map onto webhookUnwrap methods:
| Fern | Scalar |
|---|---|
x-fern-webhook-signature at the document root |
signatureAlgorithm, signatureHeader, timestampHeader and toleranceSeconds on the starter unwrap method |
x-fern-webhook-signature on one webhook |
A further webhookUnwrap method, unwrap_<first event>, whose eventTypes claims the webhooks sharing those settings |
x-fern-webhook: true on a paths operation |
The operation is dropped from the SDK, so no client method POSTs to your users' receivers |
A signature block whose algorithm has no Scalar value, such as HMAC-SHA384 or ECDSA, is dropped whole and the helper keeps the default settings. A webhook with no signature block at all still verifies with the defaults; set webhookKeyOpt: false yourself if your API does not sign it. An x-fern-webhook operation's payload type is not recovered, so move such operations into the OpenAPI 3.1 top-level webhooks block. See OpenAPI Extensions.
Diagnostics
| Code | Severity | What it means |
|---|---|---|
Config/WebhookTypeNameConflict |
warn |
A helper's typeName does not end in Event, or names a type the SDK already declares. The helper keeps its default union name. |
Config/WebhookHelperNameUnsafe |
warn |
A helper's helpers.parseUnsafe takes a verifying companion's name, so the decoder that skips verification is not generated. |
Config/WebhookUnknownEventType |
warn |
An eventTypes key names no webhook event in the document, so it selects nothing. The message lists the document's event names and suggests the one the key most likely meant, such as the operationId of the webhook the key names by its webhooks key. |
Config/WebhookHelperNoEvents |
warn |
A helper matches no webhook event, such as an empty eventTypes map on a document with no top-level webhooks, so it has nothing to decode. |
Unsupported/WebhookSignatureAlgorithm |
warn |
A target cannot verify a helper's signatureAlgorithm. The message says what that SDK does instead, per the table in Signature settings: C++ generates no method for the helper, TypeScript, Python, Swift, Ruby, Java and Kotlin throw, Go returns an error from every verifying method, Dart throws when given headers, PHP whenever it has headers or a secret, and Rust generates no verifier for the helper. |
Unsupported/WebhookSignatureSettings |
warn |
A helper configures signature header names or a toleranceSeconds that a target does not apply to it. Every target with a webhook helper reads the configured values, so nothing is reported yet; TypeScript, Python and Go apply one helper's header names to every helper their top-level webhooks module serves, with the narrowest window among them, which is not reported either (see the table above). |
See Diagnostics for how findings are graded, suppressed, and used to fail a build.
Configuration reference
Every key the webhook block of a kind: webhookUnwrap method takes, its default, and each rule the config is checked against. It is generated from the config schema, so it always matches what the generator accepts; the sections above explain what each key does in each target.
webhook.eventTypes
Type: Record<string, string>
Required
Events this helper decodes, keyed by each event's name: the webhook operation's operationId when it has one, otherwise the webhook's key under webhooks. Only the keys select events; the value is descriptive. An empty map selects every top-level webhook. A key that names no event selects nothing and is reported with a Config/WebhookUnknownEventType warning.
webhook.webhookKeyOpt
Type: string | false
Client option containing the webhook signing key, or false when verification is disabled.
webhook.signatureAlgorithm
Type: "hmac-sha1" | "hmac-sha256" | "hmac-sha512" | "ed25519" | "rsa-sha256"
Signature verification algorithm for generated webhook helpers. Defaults to hmac-sha256 when verification is enabled.
Default: "hmac-sha256"
webhook.signatureHeader
Type: string
Header carrying the webhook signature. Defaults to webhook-signature when verification is enabled.
Default: "webhook-signature"
webhook.timestampHeader
Type: string
Header carrying the webhook timestamp, when replay protection uses one.
webhook.toleranceSeconds
Type: number
Allowed timestamp skew in seconds for replay protection.
webhook.discriminator
Type: string
Payload property used to discriminate webhook event variants.
webhook.description
Type: string
Description surfaced on generated webhook helpers.
webhook.summary
Type: string
Summary surfaced on generated webhook helpers.
webhook.keyParam
Type: string
Experimental: may change in a later release. Name of the per-call argument that overrides the client's signing key, before target casing, e.g. secret. Defaults to key. TypeScript, Python and Ruby name that argument of the parse method and its verifying companions with it. The other targets keep their own spelling: Java, Kotlin, PHP, Swift and Dart already call it secret, and the rest take the key positionally. It must be a lowercase snake_case identifier, with no leading, trailing or doubled underscore (target casing drops those, so payload_ would become payload), that is not headers, body, payload, a keyword of a generated language, or a name the generated helpers already bind (wh, json, cast, get_required_header, …).
Constraints: pattern: ^(?!(?:headers|body|payload|options|opts|self|this|cls|class|def|end|and|or|not|in|is|if|else|elif|elsif|for|while|do|return|function|fun|var|val|let|const|new|delete|default|import|export|from|async|await|yield|lambda|none|true|false|null|nil|super|case|switch|try|catch|finally|throw|raise|with|as|pass|break|continue|global|nonlocal|typeof|instanceof|void|enum|interface|package|private|protected|public|static|module|begin|rescue|ensure|then|unless|until|when|redo|retry|undef|alias|defined|object|type|func|go|select|struct|chan|map|range|defer|fallthrough|goto|next|assert|del|except|extends|implements|debugger|arguments|eval|undefined|nan|infinity|wh|exc|json|cast|dict|isinstance|str|bytes|signed_headers|construct_type|get_required_header|verify_webhook_signature|refuse_unverifiable_algorithm|empty_key|b64decode|parsed)$)[a-z](?:_?[a-z0-9])*$
webhook.bytesKey
Type: "raw" | "utf8"
Experimental: may change in a later release. How the Python parse method reads a per-call key passed as bytes; its verifying companions always use bytes as the raw HMAC key. raw (the default) uses the bytes as the HMAC key itself, as the Standard Webhooks library does. utf8 decodes them as UTF-8 and reads the text as a str key is read: an optional whsec_ prefix stripped, the rest base64-decoded. Set utf8 when callers pass the dashboard's secret as bytes (read from a file or os.environb). Only Python distinguishes a bytes key; the other targets take the key as a string and ignore this.
Default: "raw"
webhook.typeName
Type: string
Experimental: may change in a later release. Name of the event union this helper returns, before target casing, e.g. ParsedWebhookEvent. Omit it to keep each target's own default, which for some targets follows the method name (parse_pet → ParsePetWebhookEvent) and for others is ParsedWebhookEvent on the top-level helper whatever the method is called. Set it when renaming the parse method must not rename the type callers already import. It applies to every target that honors it, so a target whose default differs (Rust's WebhookEvent) takes the configured name as well. It must end in Event (ParsedWebhookEvent, webhook_event), which keeps it clear of the runtime classes, params and response types, services and language built-ins each target declares on its own. A name a model, a webhook event, another webhook helper's union (its configured name or its default), or a websocket event type (ReconnectingEvent, <Method>ClientEvent, <Method>ServerEvent) already takes (compared ignoring case and separators) is ignored with a Config/WebhookTypeNameConflict warning, and a target may still keep its default where the name would clash with a type only it mints. Go always keeps its default envelope names, since every envelope-derived type shares one package with the models and their nested types.
Constraints: pattern: [Ee]vent$
webhook.helpers
Type: boolean | object
Experimental: may change in a later release. Companion methods generated next to this parse method. true (the default) adds verify_signature (checks the signature only, and only when verification is enabled) and parse_unsafe (returns the typed event without verifying). false generates the parse method alone. An object turns each companion on or off, or renames it. A companion named like the parse method or another companion is left out, and so is a parseUnsafe named like a verifying companion (verify_signature, unwrap, or the names given to them), with a Config/WebhookHelperNameUnsafe warning. Where the name clashes with another member of the generated class — a method of the same resource, a second helper there — the target resolves it as its own naming rules do, leaving the companion out or qualifying its name (see the target's guide). C# generates no companions because it renders no parse method. Dart and C++ ignore this setting: Dart generates the parse method alone, and C++ always adds a decode-only <method>_unverified twin beside it and no other companion. Rust keeps each helper's verify_signature function even with false, since it is that helper's only verifier (the top-level helper's in webhooks, and, when helpers sign differently, each other helper's in its own module). Beside a top-level parse method named anything else, Go keeps a Parsed alias and Ruby a parsed(payload, headers:, key:) alias that forward to it, unless another member of the class (a companion, a second helper, a child resource) takes that name.
Default: true
verifySignature
Type: boolean | string
Method that verifies a delivery's signature, throwing when it does not verify. It returns nothing, except in Ruby, where it returns the verified payload parsed into a hash with symbol keys. true names it verify_signature, a string names it, false omits it (Rust keeps each helper's verify_signature function either way, as that helper's only verifier). Never generated beside a parse method that does not verify.
Default: true
parseUnsafe
Type: boolean | string
Method that decodes a delivery into the typed event without verifying its signature, for tests or a body verified elsewhere. true names it parse_unsafe, a string names it, false omits it.
Default: true
unwrap
Type: boolean | string
Method that verifies a delivery's signature and returns the decoded JSON untyped. Off by default; true names it unwrap, a string names it. Never generated beside a parse method that does not verify.
Default: false
Related
- Configuration —
resources, methods, and theclientSettings.optsentry that holds the secret - OpenAPI Extensions — the Fern extensions a webhook import reads
- Diagnostics — what a build reports about a webhook helper
What did you think of this content?