Skip to main content

​
Quick Start Guide

Get your GitHub Webhook Server up and running in minutes. This guide will walk you through the essential steps to deploy and test your webhook server.
This quickstart uses container deployment (recommended). For other installation methods, see Installation.

​
Prerequisites Check

Before starting, ensure you have:
  • Container runtime (Podman or Docker) installed
  • GitHub Personal Access Token with admin rights to your repositories
  • GitHub App created (or use PAT for initial testing)
  • Public URL for webhook delivery (or use smee.io for testing)

​
Step-by-Step Setup

1

Pull the Container Image

Pull the latest stable release from GitHub Container Registry:
podman pull ghcr.io/myk-org/github-webhook-server:latest
For development, you can use smee.io as a webhook proxy to route GitHub webhooks to your local machine.
2

Create Data Directory and Configuration

Create a directory for your configuration and logs:
mkdir -p ~/webhook_server_data/logs
cd ~/webhook_server_data
Create config.yaml with minimal configuration:
config.yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/myk-org/github-webhook-server/refs/heads/main/webhook_server/config/schema.yaml

github-app-id: 123456  # Your GitHub App ID
webhook-ip: https://your-domain.com/webhook_server  # Full URL with path
# For local testing: https://smee.io/your-channel

github-tokens:
  - ghp_your_github_token_here

repositories:
  my-repository:
    name: my-org/my-repository
    protected-branches:
      main: []
Replace github-app-id, webhook-ip, and github-tokens with your actual values. The schema URL enables IDE autocompletion.
3

Start the Webhook Server

Run the container with your configuration:
podman run -d \
  --name github-webhook-server \
  -p 5000:5000 \
  -v ~/webhook_server_data:/home/podman/data:Z \
  -e WEBHOOK_SECRET=your-webhook-secret \
  -e VERIFY_GITHUB_IPS=1 \
  ghcr.io/myk-org/github-webhook-server:latest
Verify the server is running:
curl http://localhost:5000/webhook_server/healthcheck
Expected response:
{
  "status": 200,
  "message": "Alive"
}
4

Configure GitHub Webhook

Set up the webhook in your GitHub repository:
  1. Navigate to your repository settings on GitHub
  2. Click Webhooks → Add webhook
  3. Configure the webhook:
    • Payload URL: https://your-domain.com/webhook_server
    • Content type: application/json
    • Secret: Your webhook secret (same as WEBHOOK_SECRET env var)
    • Events: Select “Send me everything” or choose specific events:
      • Pull requests
      • Issue comments
      • Push
      • Pull request reviews
      • Check runs
  4. Click Add webhook
For production, always use HTTPS and configure WEBHOOK_SECRET for signature verification.
5

Test Webhook Delivery

Create a test pull request to verify webhook processing:
# In your repository
git checkout -b test-webhook
echo "Test webhook" > test.txt
git add test.txt
git commit -m "test: verify webhook integration"
git push origin test-webhook
Create a pull request on GitHub, then check the logs:
# View container logs
podman logs -f github-webhook-server
# or
docker logs -f github-webhook-server

# View webhook processing logs
tail -f ~/webhook_server_data/logs/webhooks_*.json
You should see:
  • Webhook received and queued for processing
  • PR labels added (size label, branch label)
  • Reviewer assignment (if OWNERS file exists)
  • Check runs created
6

Try Interactive Commands

Test the webhook server by commenting on your pull request:
# In the PR comments, try these commands:
/verified
The server should:
  • Add a verified label to the PR
  • Update the can-be-merged check status
  • Respond with a confirmation comment
See all available commands in the User Commands section.

​
Verify Installation

​
Check Server Health

curl http://localhost:5000/webhook_server/healthcheck

​
View Recent Webhooks

If log viewer is enabled (ENABLE_LOG_SERVER=true): 
curl "http://localhost:5000/logs/api/entries?limit=10"

​
Test Webhook Delivery

In GitHub repository settings:
  1. Go to Webhooks
  2. Click on your webhook
  3. Scroll to Recent Deliveries
  4. Click Redeliver on any delivery to test

​
User Commands

Interact with pull requests through comment-based commands:
CommandDescriptionExample
/verifiedMark PR as verified/verified
/verified cancelRemove verification/verified cancel
/approveApprove PR/approve
/holdBlock PR merging/hold
/hold cancelUnblock PR merging/hold cancel
/retest allRun all configured tests/retest all
/cherry-pick branch1 branch2Cherry-pick to branches/cherry-pick v1.0 v2.0
/test-oracleRequest AI test recommendations/test-oracle
Commands are processed in real-time as you comment on pull requests. Check the webhook logs to see processing status.

​
Common Configuration

​
Enable Pre-commit Checks

config.yaml
repositories:
  my-repository:
    name: my-org/my-repository
    pre-commit: true  # Run pre-commit on PRs
    protected-branches:
      main: []

​
Configure Tox Testing

config.yaml
repositories:
  my-repository:
    name: my-org/my-repository
    tox:
      main: all              # Run all tests for main branch PRs
      develop: unit,integration  # Run specific envs for develop
    tox-python-version: "3.12"
    protected-branches:
      main: []

​
Set Minimum Approvals

config.yaml
repositories:
  my-repository:
    name: my-org/my-repository
    minimum-lgtm: 2  # Require 2 approvals
    conventional-title: "feat,fix,docs,refactor,test"
    protected-branches:
      main: []

​
Next Steps

Configuration

Explore advanced configuration options for automation, CI/CD, and security

OWNERS Files

Set up OWNERS files for intelligent reviewer assignment

User Commands

Learn all available commands for PR and repository management

Deployment

Production deployment with Docker Compose, Kubernetes, or Systemd

​
Troubleshooting

​
Webhook Not Received

  1. Check GitHub webhook delivery status in repository settings
  2. Verify firewall allows incoming connections on port 5000
  3. Ensure webhook-ip in config matches GitHub webhook URL
  4. Check container logs: podman logs github-webhook-server

​
Commands Not Working

  1. Verify user is in repository collaborators or OWNERS file
  2. Check if PR is in draft state (most commands blocked on drafts)
  3. Review webhook logs for error messages
  4. Ensure GitHub token has required permissions

​
Health Check Fails

# Check container is running
podman ps | grep github-webhook-server

# View container logs
podman logs --tail 50 github-webhook-server

# Check port binding
ss -tlnp | grep 5000
For production deployments, see Security Best Practices to configure IP allowlisting, signature verification, and authentication.

Build docs developers (and LLMs) love

Get started for freeTalk to us