How to Test GitHub Webhooks

Whether you are building a custom CI/CD pipeline, an issue tracker, or a discord notification bot, GitHub webhooks are the engine that makes it work. GitHub can send a webhook for almost any event that occurs in a repository or organization.

Testing these webhooks requires understanding the payload structure and setting up a way to receive those payloads securely. Here is how to test GitHub webhooks efficiently.

Understanding GitHub webhook events

GitHub categorizes events by action. The most common events are "push" (when someone commits code), "pull_request" (when a PR is opened or closed), and "issues" (when an issue is created or commented on).

When an event occurs, GitHub sends an HTTP POST request to your server. The most important HTTP header is "X-GitHub-Event", which tells you exactly what type of event triggered the webhook.

The JSON payload inside the request is incredibly detailed. A single "push" event payload includes the repository details, the user who pushed the code, an array of all the individual commits, and the branch reference. This depth of data is powerful, but parsing a 300-line JSON object manually to find a single commit message is tedious.

Setting up a test endpoint

Before writing code to handle the webhook, you need to see exactly what GitHub is sending. If you point GitHub directly at your production server while you are still experimenting, you risk causing errors or polluting your database.

Instead, use a dedicated webhook inspector like Payloader.

1. Create a new endpoint URL in Payloader.
2. Go to your GitHub repository settings, click "Webhooks", and add the URL.
3. Select the specific events you want to listen to (like "push" or "pull_request").

GitHub will immediately send a "ping" event to verify the endpoint is working.

Making sense of the payload

When you push code to your repository, GitHub will fire the webhook to your Payloader URL. Instead of just dumping the raw JSON on your screen, Payloader's intelligence engine automatically formats it.

You will see a clean, human-readable summary. For a push event, it will tell you the pusher's name, the repository, the branch, and the number of commits. This allows you to understand the structure of the data immediately, so you know exactly which JSON keys to target in your code.

Routing to your local machine

Once you know what the payload looks like, you need to write the code that handles it. But GitHub cannot send a webhook to "localhost".

You can use Payloader's forwarding feature to solve this. Configure Payloader to proxy incoming GitHub requests to your local development server. Payloader will catch the public webhook from GitHub and push it down to your local machine in real time.

If your local code throws an error, you do not need to make another arbitrary code commit to trigger a new GitHub push event. You can simply hit the "Replay" button in Payloader to resend the exact same webhook to your local server until your code works perfectly.

Securing your integration

GitHub includes a security feature called a Webhook Secret. When you configure the webhook in GitHub, you can provide a secret string. GitHub uses this string to generate an HMAC signature of the payload, which it sends in the "X-Hub-Signature-256" header.

Your application should always compute its own hash of the request body using the shared secret and compare it to the header. This ensures the request genuinely came from GitHub and prevents malicious actors from triggering your CI/CD pipelines with fake requests.