Skip to content
Stainless Stainless Stainless
FeedbackDashboard
Getting started
Configure SDKs
Add webhook helpers

Webhooks

Generate webhook helpers that parse and verify webhook payloads. Support Standard Webhooks signatures with HMAC-SHA256 verification for secure event handling.

If your OpenAPI specification includes a top-level webhooks section, Stainless can generate a helper function to convert your webhook events into the types you defined.

app.post('/webhook', async (req, res) => {
  const event: MyWebhookEvent = client.webhooks.unwrap(
    req.body.toString(),
    req.headers,
  );
  ...
});

To do so, add a method to your Stainless config using the type webhook_unwrap:

resources:
  webhooks:
    methods:
      unwrap:
        type: webhook_unwrap
        discriminator: event_type

This will generate client.webhooks.unwrap(payload), a method that parses HTTP payloads. The discriminator is the name of the field used to differentiate between the various payloads in your webhooks specification (if multiple are specified).

Webhook verification

Section titled “Webhook verification”

Stainless also supports the Standard Webhooks specification. If the webhook requests do include valid webhook-id, webhook-timestamp, and webook-signature HMAC-SHA256 signature headers, you can also provide a key that will be used to verify the signatures and ensure they have been sent by an authorized server.

POST /webhook HTTP/1.1
Host: example.com
...
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OA=
webhook-timestamp: 1614265330
webhook-id: msg_p5jXN8AQM9LWM0D4loKWxJek
...

Here is an example Stainless configuration:

resources:
  webhooks:
    methods:
      unwrap:
        type: webhook_unwrap         # The literal string "webhook_unwrap"
        discriminator: event_type    # The field used to figure out which type was sent
        webhook_key_opt: webhook_key # The name of a client option
client_settings:
  opts:
    webhook_key: # Referenced by `webhook_key_opt`
      type: string
      read_env: ORG_WEBHOOK_KEY
      nullable: true

The webhook_key_opt setting refers to the name of a client option (in this case, client_settings.opts.webhook_key) where you will store the key used to verify signatures. You can configure how this client option is loaded in the client_settings section (in the example, through the ORG_WEBHOOK_KEY environment variable) and whether or not it’s allowed to be null. A nullable key may be useful if some of your users won’t be using the webhooks feature or if users won’t have the key until after the client has been initialized. The webhook key you use must be base64-encoded and may have the optional prefix whsec_ in front of the base64 value. If a webhook_key_opt is specified for the method (and there is a client option by that name), we will generate a method for client.webhooks.unwrap(payload, headers) that requires you to pass in the webhook request’s headers for verification.