How to Set Up GitHub Webhooks for Real-Time GitZoid PR Reviews

Want instant AI code reviews the moment you open a pull request? GitHub webhooks make it possible.

Instead of running GitZoid on a schedule (like every 2 minutes), you can configure GitHub to trigger GitZoid automatically whenever a PR is created or updated. This means faster feedback, less waiting, and truly automated code reviews.

In this guide, you'll learn exactly how to set up a webhook in your GitHub repository to work with GitZoid on WaveAssist.

---

What Are GitHub Webhooks? 🎣

A webhook is like a notification system for your repository. When something happens (like opening a PR), GitHub sends a real-time HTTP request to a URL you specify.

For GitZoid, this means:

• PR opened → Webhook fires → GitZoid reviews it instantly ⚡
• No cron jobs, no waiting, no manual triggers

---

Why Use Webhooks with GitZoid? 🚀

Without Webhooks	With Webhooks
Reviews run on a schedule (e.g., every hour)	Reviews trigger instantly when PR is created
Delayed feedback	Real-time AI suggestions
Uses resources even when idle	Only runs when needed
Manual configuration	Fully automated

Webhooks = Smarter, faster, more efficient automation.

---

Prerequisites ✅

Before you start, make sure you have:

1. A GitHub repository where you want GitZoid to review PRs
2. GitZoid deployed on WaveAssist (not deployed yet? Start here)
3. Your WaveAssist webhook URL (we'll show you where to find this)
4. Admin access to your GitHub repository (needed to add webhooks)

---

Step 1: Get Your WaveAssist Webhook URL 🔗

First, you need the webhook URL from your GitZoid deployment on WaveAssist.

1. Log in to WaveAssist: https://waveassist.io
2. Go to your GitZoid agent dashboard
3. Copy your unique webhook URL

It will look something like:

https://api.waveassist.io/webhooks/your-agent-id/github

💡 Tip: Save this URL somewhere safe — you'll need to paste it into GitHub in the next step.

---

Step 2: Open Your GitHub Repository Settings ⚙️

Now let's head over to GitHub:

1. Go to your GitHub repository (the one where you want GitZoid to review PRs)
2. Click on Settings (top navigation bar)
3. In the left sidebar, click Webhooks
4. Click the Add webhook button

GitHub may ask you to confirm your password — go ahead and authenticate.

---

Step 3: Configure Your Webhook 🛠️

Now you'll see the webhook configuration form. Here's how to fill it out:

Payload URL

Paste your WaveAssist webhook URL from Step 1.

https://api.waveassist.io/webhooks/your-agent-id/github

Content Type

Select: application/json

This tells GitHub to send data in JSON format, which WaveAssist expects.

Which events would you like to trigger this webhook?

Choose: Let me select individual events

Then check only these:

• ✅ Pull requests (when PRs are opened, edited, or synchronized)
• ✅ Pull request reviews (optional, for review comments)

Uncheck all other events to avoid unnecessary triggers.

Active

Make sure the Active checkbox is ✅ checked.

This ensures the webhook will actually fire.

---

Step 4: Save Your Webhook ✅

Click the green Add webhook button at the bottom.

GitHub will:

1. Save your webhook configuration
2. Send a test ping to verify it's working
3. Show you a delivery log

---

Step 5: Verify the Webhook is Working ✔️

After saving, GitHub will show you the webhook details page.

Check Recent Deliveries

1. Scroll down to Recent Deliveries
2. You should see a ping event with a green checkmark ✅
3. Click on it to see the request/response details

Green checkmark = Success! Your webhook is configured correctly.

Red X = Error. Check the error message and verify:

• Your webhook URL is correct
• Your WaveAssist agent is running

---

Step 6: Test It Out! 🧪

Time to see your webhook in action:

1. Create a new pull request in your repository
2. Wait a few seconds
3. Check the PR — GitZoid should automatically add a review comment! 🎉

If it worked, you'll see:

• An AI-generated code review comment
• A webhook delivery logged in GitHub
• GitZoid activity in your WaveAssist dashboard

---

Webhook Configuration Summary 📋

Here's a quick reference for your webhook settings:

Setting	Value
Payload URL	https://api.waveassist.io/webhooks/your-agent-id/github
Content type	application/json
Events	Pull requests, Pull request reviews
Active	✅ Yes

---

Troubleshooting Common Issues 🔧

Webhook Not Firing?

1. Check Recent Deliveries in GitHub webhook settings
2. Look for red X's and read the error messages
3. Verify your webhook URL is correct
4. Make sure your WaveAssist agent is active and running

GitZoid Not Reviewing PRs?

• Verify your GitHub token permissions (see this guide)
• Check that your token has Pull Requests: Read & Write access
• Look at WaveAssist agent logs for errors

Test Ping Failed?

• Your webhook URL might be incorrect
• Your WaveAssist agent might not be deployed yet
• Check for typos in the URL

Multiple Reviews on One PR?

• You might have duplicate webhooks set up
• Check GitHub webhook settings and delete duplicates
• Make sure you're not also running GitZoid on a schedule

---

Webhooks vs. Scheduled Runs: Which Should You Use? 🤔

Scenario	Recommended Approach
Fast-moving team with frequent PRs	Webhooks (instant reviews)
Personal projects, occasional PRs	Scheduled (e.g., hourly) or webhooks
Testing or development	Webhooks (easier to debug)
Limited API quota	Webhooks (only runs when needed)
Legacy systems without webhook support	Scheduled runs

Our recommendation: Use webhooks for the best experience — they're faster, more efficient, and feel more "real-time."

---

Security Best Practices 🔒

When setting up webhooks, keep these security tips in mind:

1. ✅ Use HTTPS URLs only (never HTTP)
2. ✅ Limit webhook events to only what you need
3. ✅ Monitor webhook deliveries for suspicious activity
4. ✅ Use fine-grained GitHub tokens instead of classic tokens
5. ✅ Store secrets in WaveAssist — never hardcode them

Happy automating! 🚀