github-webhook-relay

Receive webhooks from a GitHub repository via WebSocket

Warning
Receiving webhooks via websockets is currently in private beta

A Node.js library that uses the same APIs as the gh webhook plugin for the GitHub CLI.

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.

Minimal example

import WebhookRelay from "github-webhook-relay";

const relay = new WebhookRelay({
  owner: "gr2m",
  repo: "github-webhooks-relay",
  events: ["issues"],
  createHookToken: process.env.GITHUB_TOKEN,
});

relay.on("webhook", ({ id, name, payload, signature, headers }) => {
  console.log("received webhook: %s", name);
});

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

relay.start();

Use with Octokit

If you want to relay webhooks to a GitHub App, you can use github-app-webhook-relay.

import { App, Octokit } from "octokit";
import WebhookRelay from "github-webhook-relay";

const MyOctokit = Octokit.defaults({
  userAgent: "my-app/1.2.3",
});

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

app.webhooks.on("issues.opened", async ({ 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!",
    }
  );

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

const relay = new WebhookRelay({
  owner: "gr2m",
  repo: "github-webhooks-relay",
  events: ["issues"],
  octokit: new MyOctokit({ auth: process.env.GITHUB_TOKEN }),
});

relay.on("webhook", app.webhooks.verifyAndReceive);

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. The list of events that the webhook should subscribe to. For a list of supported event names, see the GitHub docs.

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 secret used to sign the webhook payloads. Defaults to no secret.

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 is in case the signature needs to be verified again. Parsing the JSON and later stringifying it again bight result in a signature mismatch.

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

When creating a repository webhook using the POST /repos/{owner}/{repo}/hooks endpoint and you set name to "cli" then the response body will include a ws_url key.

You can connect to the ws_url using a WebSocket client. Note that the handshake request requires an Authorization header which will have to be set to a personal access token. Using the ws npm package the code looks like this:

const ws = new WebSocket(webSocketUrl, {
  headers: {
    Authorization: process.env.GITHUB_TOKEN,
  },
});

Once the websocket is connected, the hook can be activated by setting the active property to true using the PATCH /repos/{owner}/{repo}/hooks/{hook_id} endpoint.

Each Webhook request is received with a separate message. The message is a JSON string with a Header and Body keys. The Body is base64 encoded.

A response has to be sent back within 10s, otherwise the webhook request will be canceled and time out. No further message will be sent until a response is sent back. The response has to be a JSON string as well with the keys Status, Header, and Body. The Body value needs to be base64 encoded.

Disconnecting from the websocket will automatically delete the repository webhook.

Contributing

Please see CONTRIBUTING.md.

See also

• github-webhook-relay-cli - CLI version of this library
• github-app-webhook-relay - Webhook relay for GitHub Apps

License

ISC