@octokit/webhooks

# @octokit/webhooks > GitHub webhook events toolset for Node.js [![@latest](https://img.shields.io/npm/v/@octokit/webhooks.svg)](https://www.npmjs.com/package/@octokit/webhooks) [![Test](https://github.com/octokit/webhooks.js/workflows/Test/badge.svg)](https://github.com/octokit/webhooks.js/actions?query=workflow)  - [Usage](#usage) - [Local development](#local-development) - [API](#api) - [Constructor](#constructor) - [webhooks.sign()](#webhookssign) - [webhooks.verify()](#webhooksverify) - [webhooks.verifyAndReceive()](#webhooksverifyandreceive) - [webhooks.receive()](#webhooksreceive) - [webhooks.on()](#webhookson) - [webhooks.onAny()](#webhooksonany) - [webhooks.onError()](#webhooksonerror) - [webhooks.removeListener()](#webhooksremovelistener) - [createNodeMiddleware()](#createnodemiddleware) - [Webhook events](#webhook-events) - [emitterEventNames](#emittereventnames) - [TypeScript](#typescript) - [`EmitterWebhookEventName`](#emitterwebhookeventname) - [`EmitterWebhookEvent`](#emitterwebhookevent) - [License](#license)  `@octokit/webhooks` helps to handle webhook events received from GitHub. [GitHub webhooks](https://docs.github.com/webhooks/) can be registered in multiple ways 1. In repository or organization settings on [github.com](https://github.com/). 2. Using the REST API for [repositories](https://docs.github.com/rest/reference/repos#webhooks) or [organizations](https://docs.github.com/rest/reference/orgs#webhooks/) 3. By [creating a GitHub App](https://docs.github.com/developers/apps/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 ```js // 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](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) and [smee.io](https://smee.io/). Go to [smee.io](https://smee.io/) and <kbd>Start a new channel</kbd>. Then copy the "Webhook Proxy URL" and 1. enter it in the GitHub App’s "Webhook URL" input 2. pass it to the [EventSource](https://github.com/EventSource/eventsource) constructor, see below ```js 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`](https://github.com/EventSource/eventsource) package: install with `npm install eventsource`, then `import EventSource from "eventsource";)` ## API 1. [Constructor](#constructor) 2. [webhooks.sign()](#webhookssign) 3. [webhooks.verify()](#webhooksverify) 4. [webhooks.verifyAndReceive()](#webhooksverifyandreceive) 5. [webhooks.receive()](#webhooksreceive) 6. [webhooks.on()](#webhookson) 7. [webhooks.onAny()](#webhooksonany) 8. [webhooks.onError()](#webhooksonerror) 9. [webhooks.removeListener()](#webhooksremovelistener) 10. [createNodeMiddleware()](#createnodemiddleware) 11. [createWebMiddleware()](#createwebmiddleware) 12. [Webhook events](#webhook-events) 13. [emitterEventNames](#emittereventnames) ### Constructor ```js new Webhooks({ secret /*, transform */ }); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>secret</code> (String) </td> <td> Required. Secret as configured in GitHub Settings. </td> </tr> <tr> <td> <code>transform</code> (Function) </td> <td> Only relevant for <a href="#webhookson"><code>webhooks.on</code></a>. Transform emitted event before calling handlers. Can be asynchronous. </td> </tr> <tr> <td> <code>log</code> object </td> <td> Used for internal logging. Defaults to [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) with `debug` and `info` doing nothing. </td> </tr> </tbody> </table> Returns the `webhooks` API. ### webhooks.sign() ```js webhooks.sign(eventPayload); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>eventPayload</code> (String) </td> <td> Required. Webhook request payload as received from GitHub </td> </tr> </tbody> </table> Returns a `signature` string. Throws error if `eventPayload` is not passed. The `sign` method can be imported as static method from [`@octokit/webhooks-methods`](https://github.com/octokit/webhooks-methods.js/#readme). ### webhooks.verify() ```js webhooks.verify(eventPayload, signature); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>eventPayload</code> (String) </td> <td> Required. Webhook event request payload as received from GitHub. </td> </tr> <tr> <td> <code>signature</code> (String) </td> <td> Required. Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>. </td> </tr> </tbody> </table> 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`](https://github.com/octokit/webhooks-methods.js/#readme). ### webhooks.verifyAndReceive() ```js webhooks.verifyAndReceive({ id, name, payload, signature }); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>id</code> String </td> <td> Unique webhook event request id </td> </tr> <tr> <td> <code>name</code> String </td> <td> Required. Name of the event. (Event names are set as <a href="https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers"><code>X-GitHub-Event</code> header</a> in the webhook event request.) </td> </tr> <tr> <td> <code>payload</code> String </td> <td> Required. Webhook event request payload as received from GitHub. </td> </tr> <tr> <td> <code>signature</code> (String) </td> <td> Required. Signature string as calculated by <code><a href="#webhookssign">webhooks.sign()</a></code>. </td> </tr> </tbody> </table> Returns a promise. Verifies event using [webhooks.verify()](#webhooksverify), then handles the event using [webhooks.receive()](#webhooksreceive). Additionally, if verification fails, rejects the returned promise and emits an `error` event. Example ```js 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() ```js webhooks.receive({ id, name, payload }); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>id</code> String </td> <td> Unique webhook event request id </td> </tr> <tr> <td> <code>name</code> String </td> <td> Required. Name of the event. (Event names are set as <a href="https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers"><code>X-GitHub-Event</code> header</a> in the webhook event request.) </td> </tr> <tr> <td> <code>payload</code> Object </td> <td> Required. Webhook event request payload as received from GitHub. </td> </tr> </tbody> </table> Returns a promise. Runs all handlers set with [`webhooks.on()`](#webhookson) 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](src/event-handler/). ### webhooks.on() ```js webhooks.on(eventName, handler); webhooks.on(eventNames, handler); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>eventName</code> String </td> <td> Required. Name of the event. One of <a href="#webhook-events">GitHub's supported event names</a>, or (if the event has an action property) the name of an event followed by its action in the form of <code><event>.<action></code>. </td> </tr> <tr> <td> <code>eventNames</code> Array </td> <td> Required. Array of event names. </td> </tr> <tr> <td> <code>handler</code> Function </td> <td> Required. Method to be run each time the event with the passed name is received. the <code>handler</code> function can be an async function, throw an error or return a Promise. The handler is called with an event object: <code>{id, name, payload}</code>. </td> </tr> </tbody> </table> The `.on()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/). ### webhooks.onAny() ```js webhooks.onAny(handler); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>handler</code> Function </td> <td> Required. Method to be run each time any event is received. the <code>handler</code> function can be an async function, throw an error or return a Promise. The handler is called with an event object: <code>{id, name, payload}</code>. </td> </tr> </tbody> </table> The `.onAny()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/). ### webhooks.onError() ```js webhooks.onError(handler); ``` If a webhook event handler throws an error or returns a promise that rejects, an error event is triggered. You can use this handler for logging or reporting events. The passed error object has a .event property which has all information on the event. Asynchronous `error` event handler are not blocking the `.receive()` method from completing. <table width="100%"> <tbody valign="top"> <tr> <td> <code>handler</code> Function </td> <td> Required. Method to be run each time a webhook event handler throws an error or returns a promise that rejects. The <code>handler</code> function can be an async function, return a Promise. The handler is called with an error object that has a .event property which has all the information on the event: <code>{id, name, payload}</code>. </td> </tr> </tbody> </table> The `.onError()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/). ### webhooks.removeListener() ```js webhooks.removeListener(eventName, handler); webhooks.removeListener(eventNames, handler); ``` <table width="100%"> <tbody valign="top"> <tr> <td> <code>eventName</code> String </td> <td> Required. Name of the event. One of <a href="#webhook-events">GitHub's supported event names</a>, or (if the event has an action property) the name of an event followed by its action in the form of <code><event>.<action></code>, or '*' for the <code>onAny()</code> method or 'error' for the <code>onError()</code> method. </td> </tr> <tr> <td> <code>eventNames</code> Array </td> <td> Required. Array of event names. </td> </tr> <tr> <td> <code>handler</code> Function </td> <td> Required. Method which was previously passed to <code><a href="webhookson">webhooks.on()</a></code>. If the same handler was registered multiple times for the same event, only the most recent handler gets removed. </td> </tr> </tbody> </table> The `.removeListener()` method belongs to the `event-handler` module which can be used [standalone](src/event-handler/). ### createNodeMiddleware() ```js import { createServer } from "node:http"; import { Webhooks, createNodeMiddleware } from "@octokit/webhooks"; const webhooks = new Webhooks({ secret: "mysecret", }); const middleware = createNodeMiddleware(webhooks, { path: "/webhooks" }); createServer(async (req, res) => { // `middleware` returns `false` when `req` is unhandled (beyond `/webhooks`) if (await middleware(req, res)) return; res.writeHead(404); res.end(); }).listen(3000); // can now receive user authorization callbacks at POST /webhooks ``` The middleware returned from `createNodeMiddleware` can also serve as an `Express.js` middleware directly. <table width="100%"> <tbody valign="top"> <tr> <td> <code>webhooks</code> Webhooks instance </td> <td> Required. </td> </tr> <tr> <td> <code>path</code> string </td> <td> Custom path to match requests against. Defaults to <code>/api/github/webhooks</code>. </td> </tr> <tr> <td> <code>log</code> object </td> <td> Used for internal logging. Defaults to [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) with `debug` and `info` doing nothing. </td> </tr> <tbody> </table> ### createWebMiddleware() ```js import { Webhooks, createWebMiddleware } from "@octokit/webhooks"; const webhooks = new Webhooks({ secret: "mysecret", }); const middleware = createWebMiddleware(webhooks, { path: "/webhooks" }); // Example usage in Deno Deno.serve({ port: 3000 }, middleware); ``` The middleware returned from `createWebMiddleware` can also be used in serverless environments like AWS Lambda, Cloudflare Workers, and Vercel. <table width="100%"> <tbody valign="top"> <tr> <td> <code>webhooks</code> Webhooks instance </td> <td> Required. </td> </tr> <tr> <td> <code>path</code> string </td> <td> Custom path to match requests against. Defaults to <code>/api/github/webhooks</code>. </td> </tr> <tr> <td> <code>log</code> object </td> <td> Used for internal logging. Defaults to [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) with `debug` and `info` doing nothing. </td> </tr> <tbody> </table> ### Webhook events See the full list of [event types with example payloads](https://docs.github.com/developers/webhooks-and-events/webhook-events-and-payloads/). If there are actions for a webhook, events are emitted for both, the webhook name as well as a combination of the webhook name and the action, e.g. `installation` and `installation.created`.  | Event | Actions | | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`branch_protection_configuration`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#branch_protection_configuration) | `disabled` `enabled` | | [`branch_protection_rule`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#branch_protection_rule) | `created` `deleted` `edited` | | [`check_run`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#check_run) | `completed` `created` `requested_action` `rerequested` | | [`check_suite`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#check_suite) | `completed` `requested` `rerequested` | | [`code_scanning_alert`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#code_scanning_alert) | `appeared_in_branch` `closed_by_user` `created` `fixed` `reopened` `reopened_by_user` | | [`commit_comment`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#commit_comment) | `created` | | [`create`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#create) | | | [`custom_property`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#custom_property) | `created` `deleted` `promote_to_enterprise` `updated` | | [`custom_property_values`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#custom_property_values) | `updated` | | [`delete`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#delete) | | | [`dependabot_alert`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#dependabot_alert) | `auto_dismissed` `auto_reopened` `created` `dismissed` `fixed` `reintroduced` `reopened` | | [`deploy_key`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#deploy_key) | `created` `deleted` | | [`deployment`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#deployment) | `created` | | [`deployment_protection_rule`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#deployment_protection_rule) | `requested` | | [`deployment_review`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#deployment_review) | `approved` `rejected` `requested` | | [`deployment_status`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#deployment_status) | `created` | | [`discussion`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#discussion) | `answered` `category_changed` `closed` `created` `deleted` `edited` `labeled` `locked` `pinned` `reopened` `transferred` `unanswered` `unlabeled` `unlocked` `unpinned` | | [`discussion_comment`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#discussion_comment) | `created` `deleted` `edited` | | [`fork`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#fork) | | | [`github_app_authorization`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#github_app_authorization) | `revoked` | | [`gollum`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#gollum) | | | [`installation`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#installation) | `created` `deleted` `new_permissions_accepted` `suspend` `unsuspend` | | [`installation_repositories`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#installation_repositories) | `added` `removed` | | [`installation_target`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#installation_target) | `renamed` | | [`issue_comment`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#issue_comment) | `created` `deleted` `edited` | | [`issues`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#issues) | `assigned` `closed` `deleted` `demilestoned` `edited` `labeled` `locked` `milestoned` `opened` `pinned` `reopened` `transferred` `typed` `unassigned` `unlabeled` `unlocked` `unpinned` `untyped` | | [`label`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#label) | `created` `deleted` `edited` | | [`marketplace_purchase`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#marketplace_purchase) | `cancelled` `changed` `pending_change` `pending_change_cancelled` `purchased` | | [`member`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#member) | `added` `edited` `removed` | | [`membership`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#membership) | `added` `removed` | | [`merge_group`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#merge_group) | `checks_requested` `destroyed` | | [`meta`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#meta) | `deleted` | | [`milestone`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#milestone) | `closed` `created` `deleted` `edited` `opened` | | [`org_block`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#org_block) | `blocked` `unblocked` | | [`organization`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#organization) | `deleted` `member_added` `member_invited` `member_removed` `renamed` | | [`package`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#package) | `published` `updated` | | [`page_build`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#page_build) | | | [`personal_access_token_request`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#personal_access_token_request) | `approved` `cancelled` `created` `denied` | | [`ping`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#ping) | | | [`project`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#project) | `closed` `created` `deleted` `edited` `reopened` | | [`project_card`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#project_card) | `converted` `created` `deleted` `edited` `moved` | | [`project_column`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#project_column) | `created` `deleted` `edited` `moved` | | [`projects_v2`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#projects_v2) | `closed` `created` `deleted` `edited` `reopened` | | [`projects_v2_item`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#projects_v2_item) | `archived` `converted` `created` `deleted` `edited` `reordered` `restored` | | [`projects_v2_status_update`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#projects_v2_status_update) | `created` `deleted` `edited` | | [`public`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#public) | | | [`pull_request`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request) | `assigned` `auto_merge_disabled` `auto_merge_enabled` `closed` `converted_to_draft` `demilestoned` `dequeued` `edited` `enqueued` `labeled` `locked` `milestoned` `opened` `ready_for_review` `reopened` `review_request_removed` `review_requested` `synchronize` `unassigned` `unlabeled` `unlocked` | | [`pull_request_review`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request_review) | `dismissed` `edited` `submitted` | | [`pull_request_review_comment`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request_review_comment) | `created` `deleted` `edited` | | [`pull_request_review_thread`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request_review_thread) | `resolved` `unresolved` | | [`push`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#push) | | | [`registry_package`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#registry_package) | `published` `updated` | | [`release`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#release) | `created` `deleted` `edited` `prereleased` `published` `released` `unpublished` | | [`repository`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#repository) | `archived` `created` `deleted` `edited` `privatized` `publicized` `renamed` `transferred` `unarchived` | | [`repository_advisory`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#repository_advisory) | `published` `reported` | | [`repository_dispatch`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#repository_dispatch) | `sample` | | [`repository_import`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#repository_import) | | | [`repository_ruleset`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#repository_ruleset) | `created` `deleted` `edited` | | [`repository_vulnerability_alert`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#repository_vulnerability_alert) | `create` `dismiss` `reopen` `resolve` | | [`secret_scanning_alert`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#secret_scanning_alert) | `created` `publicly_leaked` `reopened` `resolved` `validated` | | [`secret_scanning_alert_location`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#secret_scanning_alert_location) | `created` | | [`secret_scanning_scan`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#secret_scanning_scan) | `completed` | | [`security_advisory`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#security_advisory) | `published` `updated` `withdrawn` | | [`security_and_analysis`](https://docs.github.com/en/webhooks/webhook-events-and-payloads#security_and_analysis) |