webhooks-methods.js

Methods to handle GitHub Webhook requests

Table of contents

usage
Methods
Contributing
License

usage

Browsers

🚧 @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

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

Node

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

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

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()`

await sign(secret, eventPayloadString);

`secret` (String)	Required. Secret as configured in GitHub Settings.
`eventPayloadString` (String)	Required. Webhook request payload as received from GitHub. If you have only access to an already parsed object, stringify it with `JSON.stringify(payload)`

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

`verify()`

await verify(secret, eventPayloadString, signature);

`secret` (String)	Required. Secret as configured in GitHub Settings.
`eventPayloadString` (String)	Required. Webhook request payload as received from GitHub. If you have only access to an already parsed object, stringify it with `JSON.stringify(payload)`
`signature` (String)	Required. Signature string as calculated by `sign()`.

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

`verifyWithFallback()`

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

`secret` (String)	Required. Secret as configured in GitHub Settings.
`eventPayloadString` (String)	Required. Webhook request payload as received from GitHub. If you have only access to an already parsed object, stringify it with `JSON.stringify(payload)`
`signature` (String)	Required. Signature string as calculated by `sign()`.
`additionalSecrets` (Array of String)	If given, each additional secret will be tried in turn.

This is a thin wrapper around 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

License

MIT