GitHub

​

Integration Guide

This guide will walk you through setting up a webhook integration between GitHub and HookFlo, enabling you to receive alerts for repository events like code pushes, pull requests, issues, and more.

• A HookFlo account with an active project
• A GitHub account with admin access to the repository or organization you want to monitor
• Basic understanding of GitHub’s workflow and repository management

​

Integration Overview

The integration process follows these key steps:

1. Set up a webhook in HookFlo
2. Configure notification channels (email/Slack)
3. Connect GitHub to HookFlo
4. Configure GitHub to send webhooks
5. Test the integration

​

Setting Up Your HookFlo Webhook

After logging into HookFlo, follow these steps to create and configure your GitHub webhook:

​

Configuring GitHub

Now that your HookFlo webhook is set up, you need to configure GitHub to send events to it:

​

Testing Your Integration

To ensure your integration is working properly:

​

Supported Events

GitHub supports a wide range of webhook events. Here are the most commonly used categories:

​

Code Events

• push: When code is pushed to a repository
• commit_comment: When a commit is commented on
• create: When a branch or tag is created
• delete: When a branch or tag is deleted
• release: When a release is published, updated, or deleted

​

Pull Request Events

• pull_request: When a pull request is opened, closed, assigned, labeled, etc.
• pull_request_review: When a review is submitted, edited, or dismissed
• pull_request_review_comment: When a comment is made on a pull request diff
• pull_request_review_thread: When a thread in a pull request review is resolved or unresolved

​

Issue Events

• issues: When an issue is opened, closed, assigned, labeled, etc.
• issue_comment: When a comment is made on an issue or pull request
• label: When a label is created, edited, or deleted

​

Repository Events

• repository: When a repository is created, archived, unarchived, etc.
• repository_import: When a repository import is completed, canceled, or failed
• repository_vulnerability_alert: When a security vulnerability alert is created, dismissed, or resolved

​

GitHub Actions Events

• workflow_job: When a workflow job is queued, completed, or failed
• workflow_run: When a workflow run is completed

​

Organization Events

• organization: When an organization is deleted, renamed, or a user is added or removed
• organization_package: When a package is published or updated
• team: When a team is created, deleted, or modified
• team_add: When a repository is added to a team

For a complete list of events, refer to the GitHub Webhook Events documentation.

​

Webhook Headers

GitHub webhooks include these important headers that HookFlo uses for verification:

• X-GitHub-Event: The type of event (e.g., push, pull_request)
• X-GitHub-Delivery: A unique identifier for the delivery
• X-Hub-Signature-256: HMAC SHA-256 signature of the payload (if secret configured)

​

Webhook Payload Structure

Here’s an example of what the webhook payload looks like for a push event:

{
  "ref": "refs/heads/main",
  "before": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
  "after": "0000000000000000000000000000000000000000",
  "repository": {
    "id": 123456,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjM0NTY=",
    "name": "my-repo",
    "full_name": "username/my-repo",
    "private": false,
    "owner": {
      "name": "username",
      "email": "user@example.com",
      "login": "username",
      "id": 12345
    },
    "html_url": "https://github.com/username/my-repo",
    "description": "Repository description"
  },
  "pusher": {
    "name": "username",
    "email": "user@example.com"
  },
  "sender": {
    "login": "username",
    "id": 12345,
    "node_id": "MDQ6VXNlcjEyMzQ1",
    "avatar_url": "https://avatars.githubusercontent.com/u/12345?v=4",
    "type": "User"
  },
  "created": false,
  "deleted": true,
  "forced": false,
  "commits": []
}

​

Advanced Configuration

​

Example: Pull Request Review Alerts via Slack

Let’s set up a complete example of notifying your team when pull requests need review:

​

Example: Critical Issue Alerts via Email

Set up alerts when issues are labeled as “critical” or “bug”:

​

Troubleshooting

​

Security Considerations

When setting up webhook integrations between GitHub and HookFlo, keep these security best practices in mind:

• Always use a webhook secret: This prevents unauthorized requests to your webhook endpoint
• Validate all webhook signatures: HookFlo does this automatically when you provide your secret
• Limit the scopes of your webhooks: Only subscribe to events you actually need
• Use HTTPS only: All webhook URLs should use encrypted connections
• Regularly audit webhook configurations: Remove unused or outdated webhooks
• Be careful with sensitive data: Consider what information is included in your notifications
• Monitor webhook activity: Regularly review webhook events for suspicious patterns

​

Congratulations! 🎉

You’ve successfully set up real-time GitHub event tracking and alerting with HookFlo! Your team can now receive immediate notifications about important repository events, helping you respond quickly to critical issues, coordinate code reviews, and stay informed about your project’s development activity.

Need more help? Contact our support team or join our Discord forum or DM me directly on X.