Skip to content

Setting Up GitHub Webhook for ArgoCD

Overview

Configure GitHub to send webhook notifications to ArgoCD when changes are pushed to the cluster-gitops repository. This enables instant synchronization instead of waiting for the polling interval (default: 3 minutes).

Prerequisites

  • ArgoCD accessible at https://argocd.camarades.net
  • Admin access to the GitHub repository (camaradesuk/cluster-gitops)
  • ArgoCD webhook secret (can be retrieved from ArgoCD configuration)

Step 1: Get ArgoCD Webhook Secret

The webhook secret is stored in the argocd-secret in the argocd namespace.

kubectl get secret argocd-secret -n argocd -o jsonpath='{.data.webhook\.github\.secret}' | base64 -d

If the secret doesn't exist, ArgoCD will generate one automatically. You can also set a custom secret:

# Generate a random secret
WEBHOOK_SECRET=$(openssl rand -hex 20)
echo $WEBHOOK_SECRET

# Store it in ArgoCD secret
kubectl patch secret argocd-secret -n argocd \
  -p "{\"data\":{\"webhook.github.secret\":\"$(echo -n $WEBHOOK_SECRET | base64)\"}}"

Step 2: Configure GitHub Webhook

  1. Go to the GitHub repository: https://github.com/camaradesuk/cluster-gitops
  2. Navigate to Settings → Webhooks → Add webhook

Webhook Configuration:

Field Value
Payload URL https://argocd.camarades.net/api/webhook
Content type application/json
Secret Paste the webhook secret from Step 1
SSL verification ✅ Enable SSL verification
Events Just the push event
Active ✅ Active
  1. Click Add webhook

Step 3: Test the Webhook

Option A: Make a Test Commit

cd /home/chris/workspace/syrf/cluster-gitops
echo "# Test webhook" >> README.md
git add README.md
git commit -m "test: verify webhook configuration"
git push

Then check: - GitHub webhook shows a successful delivery (green checkmark) - ArgoCD immediately detects the change (check Application status in UI)

Option B: Use GitHub's Test Feature

  1. In the webhook settings, click on the webhook you just created
  2. Scroll to Recent Deliveries
  3. Click Redeliver on any delivery, or use the Test button

Verification

Check Webhook Deliveries in GitHub:

  1. Go to the webhook settings
  2. Check Recent Deliveries section
  3. Look for deliveries with 200 OK response

Check ArgoCD Logs:

# Check for webhook events in ArgoCD server logs
kubectl logs -n argocd deployment/argocd-server -f | grep webhook

You should see log entries like: 

time="..." level=info msg="Received push event repo: https://github.com/camaradesuk/cluster-gitops.git, ..."

Troubleshooting

Webhook Shows 403 Forbidden

  • Verify the webhook secret matches the one in argocd-secret
  • Check that SSL verification is enabled

Webhook Shows Connection Timeout

  • Verify ArgoCD ingress is accessible: curl -I https://argocd.camarades.net
  • Check ingress-nginx is running: kubectl get pods -n ingress-nginx
  • Verify DNS: dig argocd.camarades.net should point to your cluster's LoadBalancer IP

Webhook Shows 404 Not Found

  • Ensure the payload URL is exactly: https://argocd.camarades.net/api/webhook
  • Check ArgoCD server is running: kubectl get pods -n argocd

ArgoCD Not Responding to Webhook

  • Check ArgoCD server logs: kubectl logs -n argocd deployment/argocd-server
  • Verify webhook secret in ArgoCD: kubectl get secret argocd-secret -n argocd -o yaml

Benefits of Webhooks

Without webhooks: - ArgoCD polls Git every 3 minutes (default) - 0-3 minute delay for changes to be detected - Higher API usage on GitHub

With webhooks: - Instant notification to ArgoCD (<1 second) - Changes detected immediately - Lower GitHub API usage

Additional Configuration (Optional)

Multiple Repositories

If you have multiple repositories that ArgoCD tracks (e.g., syrf monorepo), repeat Step 2 for each repository with the same webhook secret.

Repositories to configure: - camaradesuk/cluster-gitops (deployment configs) - camaradesuk/syrf (Helm charts in helm/ directory) - camaradesuk/camarades-infrastructure (if ArgoCD manages Terraform)

Webhook for Pull Requests

To enable ArgoCD PR preview environments to update immediately, configure the webhook to also send pull request events:

In GitHub webhook settings: 1. Select Let me select individual events 2. Check: ✅ Pushes, ✅ Pull requests 3. Save webhook

Security Considerations

  • Webhook secret: Keep the secret secure. It authenticates GitHub's requests to ArgoCD.
  • SSL verification: Always enable SSL verification to prevent MITM attacks.
  • Firewall rules: Ensure your cluster's LoadBalancer allows inbound HTTPS from GitHub's webhook IPs.

GitHub webhook IP ranges can be found at: https://api.github.com/meta (look for hooks array)

References