# @octokit/webhooks-methods

> Methods to handle GitHub Webhook requests

Latest version **6.0.0** (published 2025-05-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install @octokit/webhooks-methods
pnpm add @octokit/webhooks-methods
yarn add @octokit/webhooks-methods
bun add @octokit/webhooks-methods
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2025-05-20 |
| First published | 2021-04-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >= 20 |
| Dependencies | 0 |
| Unpacked size | 23.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 27 |
| Author | Gregor Martynus |
| Maintainers | octokitbot |
| Keywords | github, api, sdk, toolkit |

## Links

- npm: https://www.npmjs.com/package/@octokit/webhooks-methods
- Repository: https://github.com/octokit/webhooks-methods.js
- Homepage: https://github.com/octokit/webhooks-methods.js#readme
- Issues: https://github.com/octokit/webhooks-methods.js/issues
- npm.io page: https://npm.io/package/@octokit/webhooks-methods

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 6.0.0 (latest) — 2025-05-20
- 5.0.0-beta.6 (beta) — 2024-02-23
- 5.1.1 — 2025-02-06
- 5.1.0 — 2024-04-04
- 5.0.0 — 2024-02-23
- 5.0.0-beta.5 — 2024-02-23
- 5.0.0-beta.4 — 2024-02-23
- 5.0.0-beta.3 — 2024-02-23
- 5.0.0-beta.2 — 2024-02-17
- 5.0.0-beta.1 — 2024-02-17
- 4.1.0 — 2024-02-17
- 4.0.0 — 2023-06-12
- 3.0.3 — 2023-06-05
- 3.0.2 — 2023-01-08
- 3.0.1 — 2022-10-04
- … 3 more at https://npm.io/package/@octokit/webhooks-methods/versions

## README

# webhooks-methods.js

> Methods to handle GitHub Webhook requests

[![@latest](https://img.shields.io/npm/v/@octokit/webhooks-methods.svg)](https://www.npmjs.com/package/@octokit/webhooks-methods)
[![Build Status](https://github.com/octokit/webhooks-methods.js/workflows/Test/badge.svg)](https://github.com/octokit/webhooks-methods.js/actions?query=workflow%3ATest+branch%3Amain)

<details>
<summary>Table of contents</summary>

<!-- toc -->

- [usage](#usage)
- [Methods](#methods)
  - [`sign()`](#sign)
  - [`verify()`](#verify)
  - [`verifyWithFallback()`](#verifywithfallback)
- [Contributing](#contributing)
- [License](#license)

<!-- tocstop -->

</details>

## usage

<table>
<tbody valign=top align=left>
<tr><th>

Browsers

</th><td width=100%>

🚧 `@octokit/webhooks-methods` is not meant to be used in browsers. The webhook secret is a sensitive credential that must not be exposed to users.

Load `@octokit/webhooks-methods` directly from [esm.sh](https://esm.sh)

```html
<script type="module">
  import {
    sign,
    verify,
    verifyWithFallback,
  } from "https://esm.sh/@octokit/webhooks-methods";
</script>
```

</td></tr>
<tr><th>

Node

</th><td>

Install with `npm install @octokit/core @octokit/webhooks-methods`

```js
import { sign, verify, verifyWithFallback } from "@octokit/webhooks-methods";
```

</td></tr>
</tbody>
</table>

```js
await sign("mysecret", eventPayloadString);
// resolves with a string like "sha256=4864d2759938a15468b5df9ade20bf161da9b4f737ea61794142f3484236bda3"

await verify("mysecret", eventPayloadString, "sha256=486d27...");
// resolves with true or false

await verifyWithFallback("mysecret", eventPayloadString, "sha256=486d27...", ["oldsecret", ...]);
// resolves with true or false
```

## Methods

### `sign()`

```js
await sign(secret, eventPayloadString);
```

<table width="100%">
  <tr>
    <td>
      <code>
        secret
      </code>
      <em>(String)</em>
    </td>
    <td>
      <strong>Required.</strong>
      Secret as configured in GitHub Settings.
    </td>
  </tr>
  <tr>
    <td>
      <code>
        eventPayloadString
      </code>
      <em>
        (String)
      </em>
    </td>
    <td>
      <strong>Required.</strong>
      Webhook request payload as received from GitHub.<br>
      <br>
      If you have only access to an already parsed object, stringify it with <code>JSON.stringify(payload)</code>
    </td>
  </tr>
</table>

Resolves with a `signature` string. Throws an error if an argument is missing.

### `verify()`

```js
await verify(secret, eventPayloadString, signature);
```

<table width="100%">
  <tr>
    <td>
      <code>
        secret
      </code>
      <em>(String)</em>
    </td>
    <td>
      <strong>Required.</strong>
      Secret as configured in GitHub Settings.
    </td>
  </tr>
  <tr>
    <td>
      <code>
        eventPayloadString
      </code>
      <em>
        (String)
      </em>
    </td>
    <td>
      <strong>Required.</strong>
      Webhook request payload as received from GitHub.<br>
      <br>
      If you have only access to an already parsed object, stringify it with <code>JSON.stringify(payload)</code>
    </td>
  </tr>
  <tr>
    <td>
      <code>
        signature
      </code>
      <em>
        (String)
      </em>
    </td>
    <td>
      <strong>Required.</strong>
      Signature string as calculated by <code><a href="../sign">sign()</a></code>.
    </td>
  </tr>
</table>

Resolves with `true` or `false`. Throws error if an argument is missing.

### `verifyWithFallback()`

```js
await verifyWithFallback(
  secret,
  eventPayloadString,
  signature,
  additionalSecrets,
);
```

<table width="100%">
  <tr>
    <td>
      <code>
        secret
      </code>
      <em>(String)</em>
    </td>
    <td>
      <strong>Required.</strong>
      Secret as configured in GitHub Settings.
    </td>
  </tr>
  <tr>
    <td>
      <code>
        eventPayloadString
      </code>
      <em>
        (String)
      </em>
    </td>
    <td>
      <strong>Required.</strong>
      Webhook request payload as received from GitHub.<br>
      <br>
      If you have only access to an already parsed object, stringify it with <code>JSON.stringify(payload)</code>
    </td>
  </tr>
  <tr>
    <td>
      <code>
        signature
      </code>
      <em>
        (String)
      </em>
    </td>
    <td>
      <strong>Required.</strong>
      Signature string as calculated by <code><a href="../sign">sign()</a></code>.
    </td>
  </tr>
  <tr>
    <td>
      <code>
        additionalSecrets
      </code>
      <em>
        (Array of String)
      </em>
    </td>
    <td>
        If given, each additional secret will be tried in turn.
    </td>
  </tr>
</table>

This is a thin wrapper around [`verify()`](#verify) that is intended to ease callers' support for key rotation.
Resolves with `true` or `false`. Throws error if a required argument is missing.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/@octokit/webhooks-methods · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._