github-app-webhook-relay

Receive webhooks from a GitHub repository using websockets amended with an installation: { id } key to run GitHub Apps locally.

Warning
Receiving webhooks via websockets is currently in private beta

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.

Usage

The createHookToken option needs to be set to a token with the admin:repo_hook and/or admin:org_hook scope, depending on which you want to create.

Webhooks are injected into the passed app instance automatically and can be handled using app.webhooks.on(eventName, handler)

import { App } from "octokit";
import AppWebhookRelay from "github-app-webhook-relay";

const app = new App({
  appId: process.env.APP_ID,
  privateKey: process.env.APP_PRIVATE_KEY,
  webhooks: {
    secret: process.env.APP_WEBHOOK_SECRET,
  },
});

app.webhooks.on("issues", async ({ payload, octokit }) => {
  const { data: comment } = await octokit.request(
    "POST /repos/{owner}/{repo}/issues/{issue_number}/comments",
    {
      owner: payload.repository.owner.login,
      repo: payload.repository.name,
      issue_number: payload.issue.number,
      body: "Hello, world!",
    }
  );

  app.log.info("[app] Comment created: %s", comment.html_url);
});

const relay = new AppWebhookRelay({
  owner: "gr2m",
  repo: "github-webhooks-relay",
  createHookToken: process.env.GITHUB_TOKEN,
  app,
});

relay.on("error", (error) => {
  console.log("error: %s", error);
});

relay.start();

API

Constructor

const relay = new WebhookRelay(options);

Required. The account name of the GitHub user or organization.

When 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.

Required. app is an instance of @octokit/app or octokit's App constructor

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).

Required unless options.createHookToken is set. octokit is an instance of @octokit/core or a compatible constructor such as octokit's Octokit.

The list of events that the webhook should subscribe to. For a list of supported event names, see the GitHub docs.

Defaults to the app's subscribed events.

relay.on()

relay.on(eventName, callback);

Required. Supported events are

1. webhook - emitted when a webhook is received
2. start - emitted when the relay is started
3. stop - emitted when the relay is stopped
4. error - emitted when an error occurs

Required. The event handler.

When eventName is webhook, the callback is called with an object with the following properties:

• id - the webhook delivery GUID
• name - the name of the event
• body - the webhook payload as string†
• signature - the signature of the webhook payload††
• headers - the headers of the webhook request

No arguments are passed when eventName is set to start or stop.

When eventName is error, the callback is called with an error object.

†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.

††The signature is calculated based on the amended payload with the additional installation key

relay.start()

relay.start();

Creates the repository hook and connects to the GitHub webhook forwarding service.

relay.stop()

relay.start();

Disconnects from the GitHub webhook forwarding service and deletes the repository hook.

How it works

See how github-webhooks-relay works.

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.

github-app-webhook-relay also verifies that the given app has access to the given repository and is subscribed to the given events.

Contributing

Please see CONTRIBUTING.md.

See also

• github-webhook-relay - The webhook relay this libary is built upon

License

ISC