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

name	type	description
options.owner	string	The account login of the GitHub user or organization. When set, webhooks will be filtered for the given account only.
options.repo	string	The name of a test repository. When set, webhooks will be filtered for the given repository only.
options.app	app	Required. app is an instance of @octokit/app or octokit's App constructor
options.events	string[]	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);

name	type	description
eventName	string	Required. Supported events are webhook - emitted when a webhook is received start - emitted when the relay is started stop - emitted when the relay is stopped error - emitted when an error occurs
callback	function	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