Webhooks.js
GitHub webhook events toolset for Node.js
Install / Use
/learn @octokit/Webhooks.jsREADME
@octokit/webhooks
GitHub webhook events toolset for Node.js
@octokit/webhooks helps to handle webhook events received from GitHub.
GitHub webhooks can be registered in multiple ways
- In repository or organization settings on github.com.
- Using the REST API for repositories or organizations
- By creating a GitHub App.
Note that while setting a secret is optional on GitHub, it is required to be set in order to use @octokit/webhooks. Content Type must be set to application/json, application/x-www-form-urlencoded is not supported.
Usage
// install with: npm install @octokit/webhooks
import { Webhooks, createNodeMiddleware } from "@octokit/webhooks";
import { createServer } from "node:http";
const webhooks = new Webhooks({
secret: "mysecret",
});
webhooks.onAny(({ id, name, payload }) => {
console.log(name, "event received");
});
createServer(createNodeMiddleware(webhooks)).listen(3000);
// can now receive webhook events at /api/github/webhooks
Local development
You can receive webhooks on your local machine or even browser using EventSource and smee.io.
Go to smee.io and <kbd>Start a new channel</kbd>. Then copy the "Webhook Proxy URL" and
- enter it in the GitHub App’s "Webhook URL" input
- pass it to the EventSource constructor, see below
const webhookProxyUrl = "https://smee.io/IrqK0nopGAOc847"; // replace with your own Webhook Proxy URL
const source = new EventSource(webhookProxyUrl);
source.onmessage = (event) => {
const webhookEvent = JSON.parse(event.data);
webhooks
.verifyAndReceive({
id: webhookEvent["x-request-id"],
name: webhookEvent["x-github-event"],
signature: webhookEvent["x-hub-signature"],
payload: JSON.stringify(webhookEvent.body),
})
.catch(console.error);
};
EventSource is a native browser API and can be polyfilled for browsers that don’t support it. In node, you can use the eventsource package: install with npm install eventsource, then import EventSource from "eventsource";)
API
- Constructor
- webhooks.sign()
- webhooks.verify()
- webhooks.verifyAndReceive()
- webhooks.receive()
- webhooks.on()
- webhooks.onAny()
- webhooks.onError()
- webhooks.removeListener()
- createNodeMiddleware()
- createWebMiddleware()
- Webhook events
- emitterEventNames
- validateEventName
Constructor
new Webhooks({ secret /*, transform */ });
Used for internal logging. Defaults to console with debug and info doing nothing.
Returns the webhooks API.
webhooks.sign()
webhooks.sign(eventPayload);
Returns a signature string. Throws error if eventPayload is not passed.
The sign method can be imported as static method from @octokit/webhooks-methods.
webhooks.verify()
webhooks.verify(eventPayload, signature);
Returns true or false. Throws error if eventPayload or signature not passed.
The verify method can be imported as static method from @octokit/webhooks-methods.
webhooks.verifyAndReceive()
webhooks.verifyAndReceive({ id, name, payload, signature });
Returns a promise.
Verifies event using webhooks.verify(), then handles the event using webhooks.receive().
Additionally, if verification fails, rejects the returned promise and emits an error event.
Example
import { Webhooks } from "@octokit/webhooks";
const webhooks = new Webhooks({
secret: "mysecret",
});
eventHandler.on("error", handleSignatureVerificationError);
// put this inside your webhooks route handler
eventHandler
.verifyAndReceive({
id: request.headers["x-github-delivery"],
name: request.headers["x-github-event"],
payload: request.body,
signature: request.headers["x-hub-signature-256"],
})
.catch(handleErrorsFromHooks);
webhooks.receive()
webhooks.receive({ id, name, payload });
Returns a promise. Runs all handlers set with webhooks.on() in parallel and waits for them to finish. If one of the handlers rejects or throws an error, then webhooks.receive() rejects. The returned error has an .errors property which holds an array of all errors caught from the handlers. If no errors occur, webhooks.receive() resolves without passing any value.
The .receive() method belongs to the event-handler module which can be used standalone
