---
title: Webhooks | Stainless
description: 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](https://learn.openapis.org/examples/v3.1/webhook-example.html), 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).

The unwrap method can be located under any resource, and you’re free to use the name of your liking.

### Webhook verification

Stainless also supports the [Standard Webhooks](https://github.com/standard-webhooks/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](https://www.stainless.com/docs/configure/client#client-opts) (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.

If you want to provide both a verified and unverified method, you can specify both:

```
resources:
  webhooks:
    methods:
      unwrap:
        type: webhook_unwrap
        discriminator: event_type
        webhook_key_opt: webhook_key
      unsafe_unwrap:
        type: webhook_unwrap
        discriminator: event_type
```