Fikayo Adepoju Oreoluwa

Getting Started with GitHub Webhooks

Published Sep 3, 2021

GitHub is arguably the largest remote code hosting service in the world. It can also be argued that it is the most-used platform by developers around the world for working on both personal and team code-based projects. One of the attributes contributing to GitHub's widespread adoption is the ability to integrate the platform into development workflows, OAuth applications, CI/CD processes, and many more use cases.

In this article, we take a look at one of the strategies for integrating GitHub into external workflows and applications, known as GitHub webhooks.

What are GitHub webhooks?

Just as webhooks are being provided by many SaaS and PaaS systems for the purpose of integration, GitHub webhooks give developers the ability to integrate with the GitHub platform.

Developers can subscribe to events taking place on GitHub, for example Push events that occur when code is pushed to a repository, and respond to the event with an action.

The response action can be anything, such as making a database entry in an external application, sending an email, triggering a deployment process, and more. Actions you can perform in response to events on GitHub are only limited by your imagination.

When a subscribed event occurs on GitHub, GitHub triggers an HTTP POST request to the defined destination. This destination is specified as an HTTP URL, which is the endpoint that is to be called whenever the event occurs. This is known as the webhook URL. The endpoint handler at the webhook URL handles the action to be performed in response to the event.

GitHub also sends the payload of data about the event that triggered the webhook along with the request. Information contained in this payload can be used for action to be taken on the endpoint.

What are the differences between GitHub webhooks and GitHub actions ?

GitHub Actions is a built-in CI/CD tool for GitHub and allows developers to automate the testing and deployment of code. When new code is pushed to a GitHub repository, GitHub actions can be set up to test the code, merge it to the main repository when tests pass and also deploy the application to a destination server.

GitHub webhooks, on the other hand, are just plain subscriptions to events that take place on the repository and can be used to trigger different actions asides from CI/CD workflows.

You can use GitHub webhooks to achieve the same CI/CD operations found in GitHub Actions, however, GitHub is not responsible for the CI/CD operation. You will need to connect your CI/CD triggers to the necessary event in your repository with GitHub webhooks and use an external CI/CD server.

GitHub actions also require a configuration script to set up, whereas GitHub webhooks do not require a script.

How do I use webhooks on GitHub?

Webhooks can be configured on a GitHub organization account, a specific repository, or a GitHub App. A webhook is connected to a GitHub event type and you can configure webhooks for more than one event. Once set up, webhooks will be sent each time a subscribed event is triggered.

Here are the steps to set up a webhook on GitHub:

Navigate to the repository you want to subscribe to events on
Go to Settings → Webhooks
Click on Add webhook
Fill in the webhook form specifying your webhook URL
Subscribe to all, or only the events you're interested in
Click the Add webhook button to complete the process

See below an example of a webhook setup on GitHub.

add-webhook-github

Immediately after the webhook is created, GitHub sends a ping webhook to your endpoint. This is to test that your endpoint is live, and you can also use it to verify the expected reaction on the webhook URL.

You can create up to 20 webhooks for each organization, repository, or GitHub app you're interested in.

Webhooks can also be configured via the GitHub API through authenticated sessions.

Types of GitHub webhooks events

As mentioned earlier, each webhook is tied to an event that takes place on GitHub, so let's look at the types of events that GitHub supports. GitHub supports over a dozen event types but except in very peculiar cases, your interest will be focused on a few common ones.

Some of the common events supported by GitHub are:

Push Event: This event is triggered when one or more commits are pushed to a repository branch or tag. This is one of the most common events developers subscribe to, as a lot can be done in response to a Push Event. You can trigger tests in continuous integration pipelines, send alerts to code reviewers on your team to review the new commit, and even trigger deployments to staging and/or production servers.
Pull Request Event: This event is triggered for any activity that involves Pull Requests, for example when a Pull Request is opened, assigned, labeled, or closed, etc. The type of activity is specified in the action property of the webhook request payload.
Issues Event: Any activity related to issues causes this event to be triggered. Just like the Pull Request Event, the type of activity is specified in the action property of the payload. The issue itself is contained in the issue property. One common use case of this event is in updating an external issue tracker.
Create Event: This event is fired when a repository user creates a new branch or tag in the remote repository.

For a full list of events supported by GitHub, their description and payload properties, check out the documentation here. Familiarity with the supported events will help you get the best out of GitHub webhooks.

While subscribing for events on a repository, you might be tempted to just subscribe for every single event available. This is not advisable, as your GitHub webhooks rate limits can easily be exceeded. Your endpoint will also be burdened with a large number of irrelevant events.

Finding information on the GitHub webhooks documentation

GitHub has well-documented and exhaustive material on webhooks. However, sometimes you just need to get started quickly and you want to navigate to the information you need as fast as possible.

Below is a list of the most common pages you will be interested in:

Conclusion

GitHub webhooks further expand the range of integration that developers have with the platform. Also, they are easy to set up and highly reliable. With GitHub webhooks, you can subscribe to events that trigger workflows in your external applications, like your custom application servers, Zapier, G Suite, CI/CD servers, etc.

In this article, we dipped our toes in the water that is GitHub webhooks. In subsequent articles, we are going to be taking a closer look at using GitHub webhooks, securing them, and best practices you should be aware of.

Happy coding!