GitHub Webhooks

GitHub webhooks enable real-time event-based integration with external systems. By subscribing to specific events like push or pull_request, you can automate workflows, trigger deployments, or notify other tools.

In this guide, we'll explain how to configure, test, validate, and debug GitHub webhooks using UseWebhook, a tool for inspecting and forwarding webhook requests to your local environment.

Why use GitHub webhooks?

Webhooks are a way to receive real-time updates from external services without polling APIs. In GitHub, webhooks are triggered by specific repository events (e.g., push, pull_request) and send HTTP POST requests to a URL you configure.

Here are some benefits of using GitHub webhooks:

• Real-time updates: Automatically receive data as events happen, without polling the API.
• Scalable: Subscribe to multiple events without exceeding API rate limits.
• Custom actions: Automate workflows like CI/CD, notifications, or custom scripts.

How GitHub webhooks work

Whenever an event occurs in a GitHub repository, GitHub sends an HTTP POST request to a URL you specify. This URL is your webhook endpoint, where you receive and process the event payload.

The basic flow is as follows:

• Subscribe to Events: Choose events to track, such as push, pull_request, or issues.
• Set a Delivery URL: Provide an endpoint where GitHub can send POST requests when events occur.
• Receive Payloads: GitHub sends event data as JSON payloads to your endpoint.
• Take Action: Process the payload to trigger actions, like deploying code or updating a database.

Create a GitHub webhook

1. Navigate to your Repo Settings:
   • Go to your repository’s Settings tab.
   • Select Webhooks from the sidebar and click Add Webhook.
2. Configure Webhook Settings:
   • Payload URL: Enter your UseWebhook URL (e.g. https://usewebhook.com/<your-id>).
   • Content Type: Choose application/json.
   • Secret: Add a secret for validating webhook signatures.
   • Select Events: Pick events like push or issues.
3. Save and Test:
   • Click Add Webhook.
   • GitHub will send a ping event to verify the configuration.

Testing webhooks from your browser

Testing webhooks is crucial, but managing endpoints, payloads, and debugging can be tedious. UseWebhook simplifies this process with an intuitive interface and powerful CLI.

1. Grab your unique webhook URL (eg. https://usewebhook.com/<my-unique-id>)
2. Use this URL as your GitHub webhook endpoint
3. Once you receive events, you can inspect, replay, and debug them from your dashboard

Every request gets its own shareable URL, making it easy to collaborate with your team or share issues with support.

Replay webhooks locally

Once you've set up your webhook, you can replay events locally for testing. Here's how:

1. Start your local server to receive webhook events (eg. Django, Rails, NextJS, Laravel)
2. Use the usewebhook-cli to forward events to your local server
3. Replay specific events from history to debug issues, for example:

usewebhook --request-id <request-ID> --forward-to http://localhost:8000/webhooks

Validate webhook signatures

An important step when working with GitHub webhooks is to validate the webhook signature. This ensures that events genuinely come from GitHub and haven't been tampered with.

GitHub signs each webhook event with a secret key, which you can use to verify the event's authenticity. Here's how to validate the signature in your app:

1. Extract the X-Hub-Signature header from the incoming request
2. Compute the HMAC hash of the payload using your secret key
3. Compare the computed hash with the signature in the header
4. If they match, the event is authentic; otherwise, reject the request
5. Respond with a 200 OK status code to acknowledge receipt

Here's an example using Node.js and Express:

const crypto = require('crypto');

function validateSignature(payload, signature, secret) {
  const computedHash = `sha256=${crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')}`;

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedHash)
  );
}

app.post('/webhooks', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-hub-signature-256'];
  const secret = process.env.GITHUB_WEBHOOK_SECRET;

  if (validateSignature(payload, signature, secret)) {
    res.status(200).send('Webhook validated!');
    // Handle webhook payload
  } else {
    res.status(403).send('Invalid signature!');
  }
});

GitHub event examples

Below are some common GitHub events and example use cases:

Best practices for production

Here are some best practices to follow when working with GitHub webhooks in a production environment:

• Use HTTPS: Always use HTTPS for your webhook endpoint to ensure data privacy and security.
• Validate Signatures: Verify the authenticity of incoming events using the X-Hub-Signature header.
• Handle Retries: GitHub retries delivery of webhooks if your server doesn't respond with a 200 OK status code. Ensure idempotent handling of events to avoid duplicate actions.
• Monitor Webhooks: Set up logging and monitoring for webhook events to track performance and troubleshoot issues.
• Use Environment Variables: Store sensitive information like API keys and secrets in environment variables to prevent exposure in your codebase.
• Test Locally: Test your webhook handler locally before deploying to production to catch and fix issues early.

Wrapping it up

GitHub webhooks are a powerful tool for automating workflows and integrating with external systems.

Tools like UseWebhook make testing and debugging easier by offering features like forwarding webhooks to localhost and replaying events.

By following best practices, you can ensure your webhook implementation is robust, secure, and production-ready.