github-app-webhook-relay-polling

Receive webhooks from a GitHub app via polling

github-app-webhook-relay-polling is an alternative to github-app-webhook-relay which relies on a beta features and does not support all webhook types, such as installation or events for repositories that were created after testing started.

Usage

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-polling";

const app = new App({
  appId: process.env.APP_ID,
  privateKey: process.env.APP_PRIVATE_KEY,
  webhooks: {
    // value does not matter, but has to be set.
    secret: "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",
  app,
});

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

relay.start();

API

Constructor

const relay = new WebhookRelay(options);

The account login of the GitHub user or organization. When set, webhooks will be filtered for the given account only.

The name of a test repository. When set, webhooks will be filtered for the given repository only.

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

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();

Starts polling webhook events delivered by the app.

relay.stop()

relay.stop();

Starts polling webhook events delivered by the app.

How it works

Webhooks that were delivered by the app are retrieved using the GET /app/hook/deliveries REST API endpoint. Each webhook payload is then retrieved using the GET /app/hook/deliveries/{delivery_id} REST API endpoint.

The event is then injected into the Octokit app instance using app.webhooks.receive().

Contributing

Please see CONTRIBUTING.md.

See also

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

License

ISC