Building a GitHub App that responds to webhook events

Learn how to build a GitHub App that makes an API request in response to a webhook event.

In this article

Introduction

This tutorial demonstrates how to write code to create a GitHub App that makes an API request in response to a webhook event. Specifically, when a pull request is opened in a repository that the app was granted access to, the app will receive a pull request webhook event. Then, the app will use GitHub's API to add a comment to the pull request.

In this tutorial, you will use your computer or codespace as a server while you develop your app. Once the app is ready for production use, you should deploy your app to a dedicated server.

This tutorial uses JavaScript, but you can use any programming language that you can run on your server.

About webhooks

When you register a GitHub App, you can specify a webhook URL and subscribe to webhook events. When activity on GitHub triggers an event that your app is subscribed to, GitHub will send a webhook event to your app's webhook URL.

For example, you can subscribe your GitHub App to the pull request webhook event. When a pull request is opened in a repository that the app was granted access to, GitHub will send a pull request webhook event to your app's webhook URL. If multiple actions can trigger the event, the event payload will include an action field to indicate what type of action triggered the event. In this example, the value of action would be opened since the event was triggered because a pull request was opened.

If your app is running on a server that is listening for these webhook events, then your app can take an action when it receives a webhook event. For example, your app can use the GitHub API to post a comment to the pull request when it receives a pull request webhook event.

For more information, see Using webhooks with GitHub Apps. For information about the possible webhook events and actions, see Webhook events and payloads.

Prerequisites

This tutorial requires your computer or codespace to run Node.js version 20 or greater and npm version 6.12.0 or greater. For more information, see Node.js.

This tutorial assumes you have a basic understanding of JavaScript and ES6 syntax.

Setup

The following sections will lead you through setting up the following components:

  • A repository to store the code for your app
  • A way to receive webhooks locally
  • A GitHub App registration that is subscribed to "pull request" webhook events, has permission to add comments to pull requests, and uses a webhook URL that you can receive locally

Create a repository to store code for your app

  1. Create a repository to store the code for your app. For more information, see Creating a new repository.
  2. Clone your repository from the previous step. For more information, see Cloning a repository. You may use a local clone or GitHub Codespaces.
  3. In a terminal, navigate to the directory where your clone is stored.
  4. If the directory doesn't already include a .gitignore file, add a .gitignore file. You will add content to this file later. For more information about .gitignore files, see Ignoring files.

You will add more code to this repository in later steps.

Get a webhook proxy URL

In order to develop your app locally, you can use a webhook proxy URL to forward webhooks from GitHub to your computer or codespace. This tutorial uses Smee.io to provide a webhook proxy URL and forward webhooks.

  1. In your browser, navigate to https://smee.io/.