Webhook Configuration

Argo CD polls Git repositories every three minutes by default to detect changes. Configure webhooks to eliminate this delay and trigger immediate application refreshes when commits are pushed.

Overview

Webhooks provide event-driven updates:

Without Webhooks

Polls every 3 minutes
Up to 3 minute delay
Unnecessary API calls
Higher resource usage

With Webhooks

Instant notifications
Immediate updates
Event-driven architecture
Reduced resource usage

Webhooks are optional but recommended for production environments where fast feedback is important.

Supported Git Providers

Argo CD supports webhook notifications from:

GitHub (github.com and GitHub Enterprise)
GitLab (gitlab.com and self-hosted)
Bitbucket Cloud
Bitbucket Server (Data Center)
Azure DevOps
Gogs

Configuration Steps

Step 1: Configure Webhook in Git Provider

GitHub
GitLab
Bitbucket Cloud
Azure DevOps

Navigate to repository settings

Go to your repository → Settings → Webhooks → Add webhook

Configure webhook

Payload URL: https://argocd.example.com/api/webhook
Content type: application/json (required)
Secret: Enter a secure random string (optional but recommended)
Events: Select “Just the push event”
Active: Checked

Save webhook

Click Add webhook

When creating the webhook in GitHub, the “Content type” must be set to application/json. The default value application/x-www-form-urlencoded is not supported.

Navigate to webhook settings

Go to your project → Settings → Webhooks

Configure webhook

URL: https://argocd.example.com/api/webhook
Secret token: Enter a secure random string (optional)
Trigger: Check “Push events”
Enable SSL verification: Checked (unless using self-signed certs)

Add webhook

Click Add webhook

Navigate to webhook settings

Go to your repository → Repository settings → Webhooks → Add webhook

Configure webhook

Title: “Argo CD Webhook”
URL: https://argocd.example.com/api/webhook
Status: Active
Triggers: Select “Repository push”

Save webhook

Click Save

Bitbucket Cloud requires special handling. See Bitbucket Cloud Special Configuration below.

Create service hook

Go to Project Settings → Service hooks → + → Web Hooks

Configure trigger

Trigger on: “Code pushed”
Repository: Select your repository
Click Next

Configure action

URL: https://argocd.example.com/api/webhook
HTTP headers: Leave default
Basic authentication: Add username/password if required
Click Finish

Azure DevOps supports basic authentication. Configure credentials in the next step.

Step 2: Configure Argo CD Secret (Optional)

Configuring a webhook secret is optional but strongly recommended to prevent DDoS attacks and unauthorized webhook triggers.

Edit argocd-secret

kubectl edit secret argocd-secret -n argocd

Add webhook secret

Add the secret under stringData (no base64 encoding needed):

apiVersion: v1
kind: Secret
metadata:
  name: argocd-secret
  namespace: argocd
type: Opaque
data:
  # ... existing keys ...

stringData:
  # GitHub webhook secret
  webhook.github.secret: shhhh! it's a GitHub secret
  
  # GitLab webhook secret
  webhook.gitlab.secret: shhhh! it's a GitLab secret
  
  # Bitbucket webhook UUID
  webhook.bitbucket.uuid: your-bitbucket-uuid
  
  # Bitbucket Server webhook secret
  webhook.bitbucketserver.secret: shhhh! it's a Bitbucket server secret
  
  # Gogs webhook secret
  webhook.gogs.secret: shhhh! it's a gogs server secret
  
  # Azure DevOps basic auth
  webhook.azuredevops.username: admin
  webhook.azuredevops.password: secret-password

Save and exit

Changes take effect immediately (no restart required).

Webhook Secret Keys by Provider

Git Provider	Secret Key	Notes
GitHub	`webhook.github.secret`	Token string
GitLab	`webhook.gitlab.secret`	Token string
Bitbucket Cloud	`webhook.bitbucket.uuid`	UUID from webhook
Bitbucket Server	`webhook.bitbucketserver.secret`	Token string
Gogs	`webhook.gogs.secret`	Token string
Azure DevOps	`webhook.azuredevops.username` `webhook.azuredevops.password`	Basic auth credentials

For security, you can store webhook secrets in a separate Kubernetes Secret with the label app.kubernetes.io/part-of: argocd. Reference it using syntax: $<secret-name>:<key>

Alternative Secret Storage

Store webhook secrets in a separate secret:

apiVersion: v1
kind: Secret
metadata:
  name: webhook-secrets
  namespace: argocd
  labels:
    app.kubernetes.io/part-of: argocd
type: Opaque
stringData:
  github-secret: my-github-webhook-secret

Reference in argocd-secret:

stringData:
  webhook.github.secret: $webhook-secrets:github-secret

Bitbucket Cloud Special Configuration

Bitbucket Cloud requires additional configuration because it doesn’t include changed files in webhook payloads.

Why Special Handling?

Bitbucket Cloud webhooks lack changed file lists
Prevents Manifest Paths Annotation from working
Argo CD uses Bitbucket’s diffstat API as workaround

Requirements

Security requirement: Bitbucket Cloud callbacks only work with encrypted webhooks that include the X-Hook-UUID header.

Configure webhook UUID

Add the UUID from your Bitbucket webhook to argocd-secret:

stringData:
  webhook.bitbucket.uuid: {your-webhook-uuid}

Configure repository OAuth token (for private repos)

Argo CD uses the repository OAuth token to call Bitbucket API:

argocd repo add https://bitbucket.org/myorg/myrepo \
  --username myuser \
  --password <oauth-token>

How It Works

Webhook received with X-Hook-UUID header
UUID verified against webhook.bitbucket.uuid secret
Argo CD calls Bitbucket diffstat API to get changed files
For public repos: uses unauthenticated API client
For private repos: uses repository OAuth token
If API call fails, changed files list remains empty (graceful degradation)

Testing Webhooks

Verify Webhook Delivery

GitHub
GitLab
Bitbucket

Go to repository → Settings → Webhooks
Click on your webhook
Scroll to Recent Deliveries
Click on a delivery to see request/response
Green checkmark = successful delivery

Check Argo CD Logs

# Watch API server logs for webhook events
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-server -f | grep webhook

# Successful webhook:
# "Received webhook request"
# "Webhook processed successfully"

# Failed webhook:
# "Webhook signature verification failed"
# "Webhook secret mismatch"

Trigger Test Event

# Make a commit and push
echo "test" >> README.md
git add README.md
git commit -m "Test webhook"
git push

# Watch application refresh
argocd app get myapp --watch

# Should see immediate refresh (not wait 3 minutes)

Webhook Security

Always Use Secrets

Configure webhook secrets to verify payload authenticity and prevent unauthorized triggers.

Limit Payload Size

Set webhook.maxPayloadSizeMB in argocd-cm ConfigMap (default: 50MB) to prevent DDoS.

Use HTTPS

Always use HTTPS for webhook endpoints to encrypt data in transit.

IP Allowlisting

Restrict webhook access to known Git provider IP ranges at firewall/ingress level.

Limiting Payload Size

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  webhook.maxPayloadSizeMB: "25"  # Limit to 25MB

ApplicationSet Webhooks

ApplicationSets use separate webhook configuration for the Git Generator.

See ApplicationSet Git Generator Webhook Configuration for details.

Troubleshooting

Webhook returns 401 Unauthorized

Cause: Webhook secret mismatch or missing.Solution:

Verify secret is configured in argocd-secret
Ensure secret matches what’s configured in Git provider
Check for typos or extra whitespace

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

Webhook received but application not refreshed

Causes:

Branch/tag mismatch in application
Application using commit SHA instead of branch
Manifest paths annotation doesn’t match changed files

Check:

# Verify application target revision
argocd app get myapp -o json | jq '.spec.source.targetRevision'

# Manually refresh to compare
argocd app get myapp --refresh

Branch and tag name collision

Issue: Webhook handler doesn’t differentiate between branch x and tag x.Impact: Push to branch x triggers refresh for apps pointing to refs/tags/x.Workaround: Use fully qualified references in applications:

spec:
  source:
    targetRevision: refs/heads/main  # Not just "main"

Payload too large error

Solution: Increase payload size limit:

# In argocd-cm ConfigMap
webhook.maxPayloadSizeMB: "100"

Advanced Configuration

Webhook Ingress Configuration

Ensure your ingress allows webhook endpoint:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  rules:
  - host: argocd.example.com
    http:
      paths:
      - path: /api/webhook
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 443

Rate Limiting

The /api/webhook endpoint currently lacks rate limiting protection. Implement rate limiting at the ingress level.

# Nginx ingress rate limiting
annotations:
  nginx.ingress.kubernetes.io/limit-rps: "10"
  nginx.ingress.kubernetes.io/limit-connections: "5"

Get Started

Installation

Core Features

Configuration

Application Management

ApplicationSet

Manifest Sources

Operations

Security

Webhook Configuration

Overview

Without Webhooks

With Webhooks

Supported Git Providers

Configuration Steps

Step 1: Configure Webhook in Git Provider

Step 2: Configure Argo CD Secret (Optional)

Webhook Secret Keys by Provider

Alternative Secret Storage

Bitbucket Cloud Special Configuration

Why Special Handling?

Requirements

How It Works

Testing Webhooks

Verify Webhook Delivery

Check Argo CD Logs

Trigger Test Event

Webhook Security

Always Use Secrets

Limit Payload Size

Use HTTPS

IP Allowlisting

Limiting Payload Size

ApplicationSet Webhooks

Troubleshooting

Advanced Configuration

Webhook Ingress Configuration

Rate Limiting

Build docs developers (and LLMs) love

Get Started

Installation

Core Features

Configuration

Application Management

ApplicationSet

Manifest Sources

Operations

Security

​Overview

Without Webhooks

With Webhooks

​Supported Git Providers

​Configuration Steps

​Step 1: Configure Webhook in Git Provider

​Step 2: Configure Argo CD Secret (Optional)

​Webhook Secret Keys by Provider

​Alternative Secret Storage

​Bitbucket Cloud Special Configuration

​Why Special Handling?

​Requirements

​How It Works

​Testing Webhooks

​Verify Webhook Delivery

​Check Argo CD Logs

​Trigger Test Event

​Webhook Security

Always Use Secrets

Limit Payload Size

Use HTTPS

IP Allowlisting

​Limiting Payload Size

​ApplicationSet Webhooks

​Troubleshooting

​Advanced Configuration

​Webhook Ingress Configuration

​Rate Limiting

​Related Resources

Build docs developers (and LLMs) love

Overview

Supported Git Providers

Configuration Steps

Step 1: Configure Webhook in Git Provider

Step 2: Configure Argo CD Secret (Optional)

Webhook Secret Keys by Provider

Alternative Secret Storage

Bitbucket Cloud Special Configuration

Why Special Handling?

Requirements

How It Works

Testing Webhooks

Verify Webhook Delivery

Check Argo CD Logs

Trigger Test Event

Webhook Security

Limiting Payload Size

ApplicationSet Webhooks

Troubleshooting

Advanced Configuration

Webhook Ingress Configuration

Rate Limiting

Related Resources