{"id":15455749,"url":"https://github.com/gr2m/github-app-webhook-relay","last_synced_at":"2025-04-21T15:51:10.450Z","repository":{"id":64195442,"uuid":"573988817","full_name":"gr2m/github-app-webhook-relay","owner":"gr2m","description":"Receive webhooks from a GitHub repository using websockets amended with an installation key for usage with GitHub Apps","archived":false,"fork":false,"pushed_at":"2025-04-01T22:45:05.000Z","size":215,"stargazers_count":4,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T10:42:06.562Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gr2m.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"gr2m"}},"created_at":"2022-12-04T03:56:18.000Z","updated_at":"2025-04-01T22:44:31.000Z","dependencies_parsed_at":"2023-12-14T04:45:41.602Z","dependency_job_id":null,"html_url":"https://github.com/gr2m/github-app-webhook-relay","commit_stats":{"total_commits":9,"total_committers":1,"mean_commits":9.0,"dds":0.0,"last_synced_commit":"f28f048176ba0270d88539312422b1023c15e7ad"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fgithub-app-webhook-relay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fgithub-app-webhook-relay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fgithub-app-webhook-relay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gr2m%2Fgithub-app-webhook-relay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gr2m","download_url":"https://codeload.github.com/gr2m/github-app-webhook-relay/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248429060,"owners_count":21101780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T22:20:38.382Z","updated_at":"2025-04-21T15:51:10.428Z","avatar_url":"https://github.com/gr2m.png","language":"JavaScript","funding_links":["https://github.com/sponsors/gr2m"],"categories":[],"sub_categories":[],"readme":"# `github-app-webhook-relay`\n\n\u003e Receive webhooks from a GitHub repository using websockets amended with an `installation: { id }` key to run GitHub Apps locally.\n\u003e\n\u003e **Warning**  \n\u003e Receiving webhooks via websockets is currently in [private beta](https://github.blog/changelog/2022-11-16-webhook-forwarding-in-the-github-cli-public-beta/)\n\n`github-app-webhook-relay` is built on top of `github-webhook-relay`. The difference is that `github-app-webhook-relay` will amend every received github webhook request's body with the `installation` key and set it to `{ id }` where `id` is the installation id of the installation ID for the given repository. Without the `installation` key the webhook event payload you cannot test GitHub Apps locally as the installation ID is required to create an installation access token in order to act as the app in a repository. Also `events` are optional and are set to the app's subscribed events by default.\n\n## Usage\n\nThe `createHookToken` option needs to be set to a [token with the `admin:repo_hook` and/or `admin:org_hook` scope](https://github.com/settings/tokens/new?scopes=admin:repo_hook,admin:org_hook\u0026description=github-webhook-relay), depending on which you want to create.\n\nWebhooks are injected into the passed `app` instance automatically and can be handled using `app.webhooks.on(eventName, handler)`\n\n```js\nimport { App } from \"octokit\";\nimport AppWebhookRelay from \"github-app-webhook-relay\";\n\nconst app = new App({\n  appId: process.env.APP_ID,\n  privateKey: process.env.APP_PRIVATE_KEY,\n  webhooks: {\n    secret: process.env.APP_WEBHOOK_SECRET,\n  },\n});\n\napp.webhooks.on(\"issues\", async ({ payload, octokit }) =\u003e {\n  const { data: comment } = await octokit.request(\n    \"POST /repos/{owner}/{repo}/issues/{issue_number}/comments\",\n    {\n      owner: payload.repository.owner.login,\n      repo: payload.repository.name,\n      issue_number: payload.issue.number,\n      body: \"Hello, world!\",\n    }\n  );\n\n  app.log.info(\"[app] Comment created: %s\", comment.html_url);\n});\n\nconst relay = new AppWebhookRelay({\n  owner: \"gr2m\",\n  repo: \"github-webhooks-relay\",\n  createHookToken: process.env.GITHUB_TOKEN,\n  app,\n});\n\nrelay.on(\"error\", (error) =\u003e {\n  console.log(\"error: %s\", error);\n});\n\nrelay.start();\n```\n\n## API\n\n### Constructor\n\n```js\nconst relay = new WebhookRelay(options);\n```\n\n\u003ctable\u003e\n  \u003cthead align=left\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        name\n      \u003c/th\u003e\n      \u003cth\u003e\n        type\n      \u003c/th\u003e\n      \u003cth width=100%\u003e\n        description\n      \u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody align=left valign=top\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003eoptions.owner\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003estring\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\n**Required**. The account name of the GitHub user or organization.\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003eoptions.repo\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003estring\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\nWhen set, the webhook will be created for the repository. When not set, the webhook will be created for the organization. Note that user-level webhooks are not supported by GitHub, so `options.owner` must be an organization.\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003eoptions.app\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003eapp\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\n**Required**. `app` is an instance of [`@octokit/app`](https://github.com/octokit/app.js/#readme) or [`octokit`'s `App` constructor](https://github.com/octokit/octokit.js/#octokit-api-client)\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003eoptions.createHookToken\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003estring\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\n**Required unless `options.octokit` is set**. Access token to create the repository webhook. The token needs to have the `admin:repo_hook` scope. ([create a personal access token](https://github.com/settings/tokens/new?scopes=admin:repo_hook\u0026description=github-webhook-relay)).\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003eoptions.octokit\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003eoctokit\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\n**Required unless `options.createHookToken` is set**. `octokit` is an instance of [`@octokit/core`](https://github.com/octokit/core.js/#readme) or a compatible constructor such as [`octokit`'s `Octokit`](https://github.com/octokit/octokit.js#octokit-api-client).\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003eoptions.events\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003estring[]\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\nThe list of events that the webhook should subscribe to. For a list of supported event names, see [the GitHub docs](https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads).\n\nDefaults to the app's subscribed events.\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n### `relay.on()`\n\n```js\nrelay.on(eventName, callback);\n```\n\n\u003ctable\u003e\n  \u003cthead align=left\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        name\n      \u003c/th\u003e\n      \u003cth\u003e\n        type\n      \u003c/th\u003e\n      \u003cth width=100%\u003e\n        description\n      \u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody align=left valign=top\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003eeventName\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003estring\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\n**Required**. Supported events are\n\n1. `webhook` - emitted when a webhook is received\n1. `start` - emitted when the relay is started\n1. `stop` - emitted when the relay is stopped\n1. `error` - emitted when an error occurs\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003cth\u003e\n        \u003ccode\u003ecallback\u003c/code\u003e\n      \u003c/th\u003e\n      \u003ctd\u003e\n        \u003ccode\u003efunction\u003c/code\u003e\n      \u003c/td\u003e\n      \u003ctd\u003e\n\n**Required**. The event handler.\n\nWhen `eventName` is `webhook`, the callback is called with an object with the following properties:\n\n- `id` - the webhook delivery GUID\n- `name` - the name of the event\n- `body` - the webhook payload as string\u003csup\u003e†\u003c/sup\u003e\n- `signature` - the signature of the webhook payload\u003csup\u003e††\u003c/sup\u003e\n- `headers` - the headers of the webhook request\n\nNo arguments are passed when `eventName` is set to `start` or `stop`.\n\nWhen `eventName` is `error`, the callback is called with an error object.\n\n\u003csub\u003e†The webhook payload is passed as string in case the signature needs to be verified. Parsing the JSON and later stringifying it again bight result in a signature mismatch.\u003c/sub\u003e\n\n\u003csub\u003e††The signature is calculated based on the amended payload with the additional `installation` key\u003c/sub\u003e\n\n\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n### `relay.start()`\n\n```js\nrelay.start();\n```\n\nCreates the repository hook and connects to the GitHub webhook forwarding service.\n\n### `relay.stop()`\n\n```js\nrelay.start();\n```\n\nDisconnects from the GitHub webhook forwarding service and deletes the repository hook.\n\n## How it works\n\nSee [how `github-webhooks-relay` works](https://github.com/gr2m/github-webhook-relay/#how-it-works).\n\n`github-app-webhook-relay` listenes to the `webhook` event of its internal `github-webhooks-relay` instance, parses the payload, adds the installation key, calculates the signature based on the new body, and then triggers its own `webhook` event.\n\n`github-app-webhook-relay` also verifies that the given app has access to the given repository and is subscribed to the given events.\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## See also\n\n- [`github-webhook-relay`](https://github.com/gr2m/github-webhook-relay/#readme) - The webhook relay this libary is built upon\n\n## License\n\n[ISC](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgr2m%2Fgithub-app-webhook-relay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgr2m%2Fgithub-app-webhook-relay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgr2m%2Fgithub-app-webhook-relay/lists"}