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

From your Hookflo Dashboard, navigate to > Manage Webhooks
Click on + Create Webhook
Your webhook will be created in an inactive state by default

Once created, you’ll see your webhook in manage webhooks table.

Setup Notification Channel

Configure Email Notifications

Toggle the Email Notifications switch to enable email alerts
In the dialog box that appears, enter the email address where you want to receive notifications
Select an email template from the dropdown menu
Click Preview Template to see how your notifications will look
Use the editor to customize the template if needed
Click Save Configuration to confirm your settings

Email notifications are perfect for critical alerts that require immediate attention and have lower usage limits. Use it for critical alerts.

Configure Slack Notifications

Toggle the Slack Notifications switch to enable Slack alerts
In the dialog box, paste your Slack webhook URL (see How to Get a Slack Webhook URL)
Keep the randomly generated name or enter a custom one (optional)
Select a notification template from the available options
Preview and edit the template as needed
Click Save Configuration to confirm your settings

Slack notifications are ideal for team collaboration and awareness. Highly recommended to use Slack as it has 3x usage limits compared to email.

Connect your Webhook with application

Configure Application

Click the Connect button to activate your webhook
Select GitHub as application to integrate
A configuration panel will appear with your webhook credentials:
- Webhook URL: The HTTP POST request endpoint GitHub will send events to
- Webhook Secret: Secret for GitHub to sign webhook payloads (optional)
Copy the Webhook URL for the next section

You can also configure notification channels from this panel if you haven’t done so already.

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

Navigate to your GitHub repository
Click on Settings in the top navigation bar
Select Webhooks from the left sidebar
Click Add webhook
Enter your HookFlo webhook URL in the Payload URL field
Set Content type to application/json
Required to Enter a secret in the Secret field
Choose which events to trigger the webhook:
- Just the push event (default)
- Send me everything
- Let me select individual events
Check the Active checkbox to enable the webhook
Click Add webhook to finalize

Configure Organization-Level Webhook

Setting Up Organization Webhooks

If you want to monitor events across all repositories in an organization:

Navigate to your GitHub organization
Click on Settings in the top navigation bar
Select Webhooks from the left sidebar
Click Add webhook
Enter your HookFlo webhook URL in the Payload URL field
Set Content type to application/json
Required to Enter a secret in the Secret field
Choose which events to trigger the webhook:
- Just the push event (default)
- Send me everything
- Let me select individual events (including organization-specific events)
Check the Active checkbox to enable the webhook
Click Add webhook to finalize

Configure Webhook Secret in HookFlo

Setting Up Webhook Verification

After creating the webhook in GitHub (If you have added secret in Github):

Return to the HookFlo dashboard
Navigate to your GitHub webhook configuration
Find the “Webhook Secret” field
Paste the same secret you entered in GitHub
Click Save Configuration

This step ensures that HookFlo can verify webhook events are genuinely from GitHub.

Testing Your Integration

To ensure your integration is working properly:

Test the Webhook in GitHub

Generating Test Events

In GitHub, go to your repository or organization’s Webhooks settings
Find your newly created webhook
Scroll to the bottom and click Redeliver on a recent delivery, or
Click Test to send a ping event
Alternatively, create a real event by pushing code, opening an issue, or creating a pull request

Verify in HookFlo

Validate Alert Delivery

Return to your HookFlo dashboard
Navigate to Notification Logs
You should see the test events appear with details about the changes
If you’ve configured notification channels, check your email or Slack for alerts

This confirms that your GitHub webhook is correctly sending events to HookFlo, and your notification channels are properly configured.

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

If you’re seeing webhook verification errors:

Double-check that you’ve entered the exact same secret in both GitHub and HookFlo
Ensure there are no extra spaces or special characters in your secret
Verify that the Content-Type in GitHub is set to application/json
Check if you’re using the correct HookFlo webhook URL

GitHub’s webhook signature is case-sensitive and must match exactly. If you’re still having issues, try generating a new secret.

Missing Events

If certain events aren’t being received:

In GitHub, go to your webhook settings and check the “Recent Deliveries” tab
Look for any failed deliveries and check their response codes
Verify that you’ve selected the specific event types in GitHub’s webhook configuration
Check your HookFlo webhook logs to see if events are being received but filtered out
For organization webhooks, ensure the repository is included in the webhook scope

Webhook Timeouts

If webhook deliveries are timing out:

GitHub expects a response within 10 seconds or it will mark the delivery as failed
GitHub will retry failed webhook deliveries up to 3 times
Check if your HookFlo webhook is processing events efficiently
Consider implementing asynchronous processing for complex event handling

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

Blogs

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

Blogs

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! 🎉

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! 🎉