GitHub webhooks provide an effective way to automate processes and trigger actions in response to events within the repositories. Whether it's a push to a branch, a new issue, or a pull request, webhooks allow you to receive real-time notifications and send payloads to external services.
In this blog post, we will try a simple project that will explain the process of creating a GitHub webhook to send payloads on every push event, receive and process those payloads using a Python server running on localhost, and make it accessible from the internet using ngrok. Additionally, we will touch upon other events that can serve as triggers for GitHub webhooks and discuss some popular use cases.
Creating a GitHub Webhook: To begin, navigate to the repository where you want to set up the webhook. Access the repository's settings and choose "Webhooks" from the left menu. Click on "Add webhook" and configure the webhook settings:
Payload URL: Set it to the publicly accessible URL where your Python server will be running (we'll use ngrok for this).
Content type: Choose "application/json" to receive payloads in JSON format.
Events: Select "Just the push event" to trigger the webhook on every push.
Receiving and Processing Payloads: Set up a Python server using a framework like Flask to receive and process the payloads sent by GitHub. Here's an example code snippet to get you started:
from flask import Flask, request app = Flask(__name__) def receive_payload(): payload = request.json # Print the received payload print("Received payload:") print(payload) return 'Payload received successfully' if __name__ == '__main__': app.run(debug=True, port=5000)
Exposing Local Server to the Internet: To make the local server accessible from the Internet, we'll use ngrok. Download and install ngrok, then run it with the following command in your terminal:
./ngrok http 5000
Ngrok will generate a publicly accessible URL, such as
http://randomstring.ngrok.io, which will forward requests to your local server on port 5000.
Configuring the Webhook with the Ngrok URL: Go back to the GitHub webhook settings and update the "Payload URL" field with the ngrok URL. Save the GitHub webhook configuration.
Test the workflow by pushing new changes to the repository. The payload received from GitHub will be printed on the terminal that runs the Python server.
Other GitHub Webhook Triggers: GitHub webhooks offer a wide range of event triggers beyond push events. Some notable ones include:
Pull requests: Trigger actions when a new pull request is opened, closed, or updated.
Issues: Respond to new issues or changes in issue status.
Repository events: Detect new forks, stars, or repository creations.
GitHub webhooks can be used to automate various tasks and streamline development workflows. They can trigger actions such as initiating builds and deployments, updating issue trackers, sending notifications to communication platforms like Slack, performing code quality checks, synchronizing repositories, updating documentation, and more.