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.

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, 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)

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);

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 and Kotlin (client.events), while TypeScript, Python and Go still generate it at client.webhooks.

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.

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.

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 path segment that names a resource your configuration already generates puts the helper beside that resource's methods; a segment that names none gets a container generated for it. Each scoped helper carries its own event set, signing secret, signature settings and companions.

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.

Leave webhookKeyOpt unset and the helper still verifies. TypeScript, Python, Go and Ruby 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.

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. 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 or Swift refuses a call without headers rather than skipping the check.

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:

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:

If your API signs with anything other than HMAC-SHA256 under the default headers, check the targets you ship against this table.

Companion methods

Beside its parse method, a helper generates companion methods:

The two verifying companions, verify_signature and unwrap, are generated only when the helper verifies; a helper with webhookKeyOpt: false gets parse_unsafe alone.

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
    }
  }
}

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 its verify_signature function even with companions off, because it is the crate's only verifier.

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 and Swift already call the argument secret, and the other targets take the key positionally, 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.

Other keys

What gets generated

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.

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 and Ruby includes a ## Webhooks section when the SDK has a webhook helper the client reaches directly, such as client.webhooks. 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; and Ruby documents it at its own path (client.notifications.webhooks). Go, Java and Kotlin reach it only through its parent resource, so they leave it to the API reference. It 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.

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 and Kotlin 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:

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

See Diagnostics for how findings are graded, suppressed, and used to fail a build.

Related

• Configuration — resources, methods, and the clientSettings.opts entry that holds the secret
• OpenAPI Extensions — the Fern extensions a webhook import reads
• Diagnostics — what a build reports about a webhook helper