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.

GitHub webhooks can be configured at either the repository or organization level, giving you flexibility in how you monitor your GitHub activity.

Hookflo only supports GitHub integration only when a secret is provided during webhook creation. Leaving the secret field empty will cause notifications to fail.Prerequisites

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:

Set up a webhook in HookFlo
Configure notification channels (email/Slack)
Connect GitHub to HookFlo
Configure GitHub to send webhooks
Test the integration

Setting Up Your HookFlo Webhook

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

Create a Webhook

Setting Up Your Webhook Endpoint

Setup Notification Channel

Configure Email Notifications

Configure Slack Notifications

Connect your Webhook with application

Configure Application

Configuring GitHub

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

Configure Repository-Level Webhook

Setting Up Repository Webhooks

Configure Organization-Level Webhook

Setting Up Organization Webhooks

Configure Webhook Secret in HookFlo

Setting Up Webhook Verification

Testing Your Integration

To ensure your integration is working properly:

Test the Webhook in GitHub

Generating Test Events

Verify in HookFlo

Validate Alert Delivery

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

Customizing Notification Templates

HookFlo allows you to fully customize your notification templates:

Email Template Example for Pull Request:

Subject: [GitHub] Pull Request {{action}} by {{sender.login}}

Hello,

A pull request was {{action}} in {{repository.full_name}}:

Title: {{pull_request.title}}
Author: {{pull_request.user.login}}
URL: {{pull_request.html_url}}

{{#if pull_request.body}}
Description:
{{pull_request.body}}
{{/if}}

Best regards,
The HookFlo Team

Slack Template Example for Code Push:

*New code pushed to {{repository.full_name}}*

Branch: {{ref}}
Pusher: {{pusher.name}}

{{#each commits}}
• <{{this.url}}|{{truncate this.id 7}}> - {{this.message}} (by {{this.author.name}})
{{/each}}

You can use any data from the webhook payload in your templates using Handlebars syntax.

Filtering Events

HookFlo allows you to filter events based on their content:

Go to Alert Rules → Create Rule
Source: Your GitHub webhook

Add conditions like:

Only alert on pull requests to the main branch:

{
  "headers.x-github-event": "pull_request",
  "pull_request.base.ref": "main"
}

Only alert on failed workflow runs:

{
  "headers.x-github-event": "workflow_run",
  "workflow_run.conclusion": "failure"
}

Configure your notification channel and template
Save the rule

This powerful filtering ensures you only receive alerts for the specific events you care about.

Example: Pull Request Review Alerts via Slack

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

Configure GitHub Webhook

Follow the steps above to create a repository webhook in GitHub
When selecting events, choose Let me select individual events
Select the following events:
- Pull request reviews
- Pull requests
Set up a secret and add it to both GitHub and HookFlo

Test the Alert

Create a pull request in your repository
Have someone (or yourself) review the PR and request changes
Check your Slack channel for the alert
Verify the formatting and content match your template

Example: Critical Issue Alerts via Email

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

Configure GitHub Webhook

Follow the steps above to create a repository webhook in GitHub
When selecting events, choose Let me select individual events
Select the Issues event
Set up a secret and add it to both GitHub and HookFlo

Test the Alert

Create an issue in your repository
Add the “critical” or “bug” label to the issue
Check your email for the alert
Verify the formatting and content match your template

Troubleshooting

Webhook Verification Failures

Missing Events

Webhook Timeouts

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.

Get Started

Platforms

Notification Channels

Security

Integration Guide

Integration Overview

Setting Up Your HookFlo Webhook

Configuring GitHub

Testing Your Integration

Supported Events

Code Events

Pull Request Events

Issue Events

Repository Events

GitHub Actions Events

Organization Events

Webhook Headers

Webhook Payload Structure

Advanced Configuration

Email Template Example for Pull Request:

Slack Template Example for Code Push:

Example: Pull Request Review Alerts via Slack

Example: Critical Issue Alerts via Email

Troubleshooting

Security Considerations

Congratulations! 🎉

Get Started

Platforms

Notification Channels

Security

​Integration Guide

​Integration Overview

​Setting Up Your HookFlo Webhook

​Configuring GitHub

​Testing Your Integration

​Supported Events

​Code Events

​Pull Request Events

​Issue Events

​Repository Events

​GitHub Actions Events

​Organization Events

​Webhook Headers

​Webhook Payload Structure

​Advanced Configuration

​Example: Pull Request Review Alerts via Slack

​Example: Critical Issue Alerts via Email

​Troubleshooting

​Security Considerations

​Congratulations! 🎉

Integration Guide

Integration Overview

Setting Up Your HookFlo Webhook

Configuring GitHub

Testing Your Integration

Supported Events

Code Events

Pull Request Events

Issue Events

Repository Events

GitHub Actions Events

Organization Events

Webhook Headers

Webhook Payload Structure

Advanced Configuration

Example: Pull Request Review Alerts via Slack

Example: Critical Issue Alerts via Email

Troubleshooting

Security Considerations

Congratulations! 🎉