GitHub - octokit/webhooks-methods.js: Methods to handle GitHub Webhook requests (original) (raw)
webhooks-methods.js
Methods to handle GitHub Webhook requests
Table of contents
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