Why Argo CD webhooks change how fast Git changes reach clusters
Argo CD refreshes each application by polling its Git repository every three minutes, which means a commit can wait up to that long before Argo CD notices it. Webhooks fix this by having the Git host notify Argo CD when a push happens, so the refresh starts when the change arrives rather than on the next timer tick. For a platform team with many applications, or one large repository feeding many of them, the polling alternative means every application repeatedly asks Git whether anything changed, which adds steady API load on the Git host and delays deployments that could have started immediately. Webhooks are the cheaper and faster default when your Git host can send them.
The supported providers are GitHub, GitLab, Bitbucket, Bitbucket Server, Azure DevOps and Gogs. Each one sends its push event to an Argo CD endpoint, and each needs its own configuration on the Git side, so the first decision is simply which hosts your repositories live on. Confirm in your own environment that the Git host can reach the Argo CD API server over the network path you plan to expose, since a webhook that cannot be delivered leaves you with polling delay and no error in the application view. Self-hosted Git servers behind private networks need the same reachability check before you rely on push notifications.
Polling alone is enough when you have a small number of applications, a repository that changes rarely, or a Git host that cannot send outbound notifications to your cluster network. In those cases a three-minute delay is usually acceptable and the added configuration is not worth it. Webhooks become worth planning when deployment speed matters, when many applications share a repository, or when Git API limits are a concern on your host. Before you enable them, read the provider-specific setup in the Argo CD Git webhook configuration guide and decide who owns the shared secrets and the endpoint exposure.
Webhook setup for each supported Git provider
GitHub is the most direct case. In the repository settings, add a webhook that posts to the webhook endpoint on your Argo CD API server, using the content type and secret that the Argo CD webhook guide specifies. The event that matters is the push event, which fires when branches or tags change, and GitHub is listed among the providers Argo CD supports.
- Where it lives: Repository settings, then the webhooks section. Organization-level webhooks can cover many repositories, but confirm the menu path in GitHub's current UI first.
- Endpoint: The Argo CD API server address plus the webhook path from the guide, served over HTTPS with a certificate that GitHub can validate.
- Events: Send push events. Add other event types only when a documented Argo CD behavior needs them.
- Shared secret: Enter the same value in the GitHub form and in the GitHub secret key in Argo CD's configuration. A mismatch causes deliveries to be rejected.
- Delivery checks: Open the recent deliveries view after a test push and read the status code and response body.
Confirm menu paths and payload options against GitHub's current interface and the Argo CD webhook guide before you rely on them.
GitLab webhooks are created in the project's settings under the webhooks section. Argo CD's guide covers GitLab, so the endpoint pattern matches the other providers, but the event selection is set one trigger at a time. For a self-managed GitLab, the most common failure is network reachability rather than configuration: GitLab must be able to open a connection to your Argo CD API server.
- Where it lives: Project settings, then webhooks. Check which levels your GitLab edition allows before you choose a project or group scope.
- Endpoint: The Argo CD API server webhook path over HTTPS, using an address that GitLab resolves from its own network.
- Events: Enable push events and tag push events. Tag events matter because Argo CD treats branch and tag names alike, as covered later in this topic.
- Shared secret: Enter a secret token in the webhook form and match it to the GitLab secret key in Argo CD's configuration.
- Certificate trust: If your internal certificate authority is not in GitLab's trust store, add it to the store and keep certificate verification enabled.
Confirm the trigger names and menu paths in your GitLab version and in the Argo CD webhook guide before you enable them.
Bitbucket Cloud and Bitbucket Server are both covered in the Argo CD guide, but they differ in who hosts the service and therefore in how Argo CD must be reached. Both are configured per repository, and both need the webhook to post to the Argo CD API server with a shared secret. Bitbucket Cloud is hosted by Atlassian, so your Argo CD endpoint must accept connections from Atlassian's outbound addresses. Bitbucket Server runs inside your network, so the path is internal.
- Where it lives: Repository settings, then webhooks. Bitbucket Server administrators may also manage webhooks at the project level. Confirm the path in your version.
- Endpoint: The Argo CD API server webhook path over HTTPS. For Bitbucket Server, use an internal address that the server can route to.
- Events: Select repository push events. Confirm the exact trigger names in the current interface.
- Shared secret: Set a secret on the webhook and match it to the Bitbucket key in Argo CD's configuration.
- Firewall policy: For Bitbucket Cloud, confirm with your network team whether inbound HTTPS from Atlassian's published ranges is permitted. For Bitbucket Server, confirm internal routes and certificate trust.
Verify each setting with a test push and the Argo CD logs.
Azure DevOps uses service hooks rather than repository-level webhook forms. In the project settings, create a subscription that sends code push events to a web hook target, and point that target at your Argo CD API server. Argo CD's guide lists Azure DevOps among its supported providers. Azure DevOps Services is cloud-hosted, while Azure DevOps Server runs in your own network, so the reachability questions differ between the two.
- Where it lives: Project settings, then service hooks. Create a new subscription and select the web hook service.
- Event: Choose the code pushed event so that branch and tag updates reach Argo CD.
- Endpoint: The Argo CD API server webhook path over HTTPS, with a certificate the Azure DevOps service can validate.
- Authentication and secret: Confirm which authentication method the Argo CD guide expects for this provider, then configure the matching value on both sides.
- Test: Use the test function in the subscription and read the response in the Argo CD logs.
Confirm the service hook interface and the authentication options in your Azure DevOps release and in the Argo CD webhook guide before you go live.
Gogs is a lightweight, self-hosted Git service, and Argo CD's guide lists it among the supported providers. Its webhook settings sit in the repository settings of the Gogs web interface. Because Gogs is always self-hosted, the network path from the Gogs server to Argo CD is the design decision that matters most, ahead of the form fields themselves.
- Where it lives: Repository settings, then webhooks. Confirm the exact menu labels in your Gogs release.
- Endpoint: The Argo CD API server webhook path over HTTPS, using a hostname that the Gogs server resolves.
- Events: Send push events for the repositories that Argo CD watches.
- Shared secret: Set a secret in the Gogs form and match it to the Gogs key in Argo CD's configuration. Confirm the key name in the Argo CD guide.
- Network and trust: Check DNS resolution, egress rules on the Gogs host, and the certificate chain that Argo CD presents.
Run a test push and check both the Gogs delivery log and the Argo CD logs to confirm the full path works.
Webhook options and when each fits
This table compares four ways to trigger Argo CD refreshes from Git: polling only, webhooks with the default poll as fallback, webhooks paired with manifest-generate-paths for monorepos, and a shared secret per provider. Read each row against refresh latency, load on the Git host's API and the ongoing effort to keep the setup correct. The main takeaway is that webhooks remove most of the delay, but they add configuration that someone must own and verify.
| Option | Refresh latency and Git load | Operational effort | When it fits |
|---|---|---|---|
| Polling only | Argo CD checks each repository on its default interval, so changes can wait for the next poll. Git API load grows with the number of repositories and applications. | Lowest. No webhook endpoints, secrets or provider settings to maintain. | Small estates with few repositories, or where the Argo CD endpoint cannot be reached from the Git host. |
| Webhooks with the default poll as fallback | Push events trigger refresh quickly. The periodic poll still runs, so a missed or failed delivery is corrected later. | Moderate. Each provider needs a webhook pointing at the Argo CD API server and a matching secret, plus checks that deliveries succeed. | Most teams with several repositories who want fast feedback and a safety net against lost deliveries. |
| Webhooks for monorepos with manifest-generate-paths | A push that touches unrelated folders does not force every application to regenerate its manifests, which reduces repo-server work on large repositories. | Higher. Each application needs correct path annotations, and teams must keep them in step as directories move. | Large monorepos where many applications share one repository and commits touch only a few paths. |
| Shared secret per provider | Does not change latency directly. It makes Argo CD reject payloads that lack a valid signature, so forged events cannot trigger refreshes. | Ongoing. Secrets must be generated, stored outside Git, rotated and configured identically on both sides. | Any webhook exposed to the internet. Treat it as required, not optional. |
| Branch and tag naming check | A branch and a tag with the same name can both trigger a refresh, so a push to branch x may refresh an application that targets refs/tags/x. | Low to moderate. Requires a naming convention and a review of target revisions. | Repositories where branches and tags could share names, or where targets use short names instead of fully qualified refs. |
Setting up webhooks in the order that avoids silent failures
This sequence confirms reachability, secures the shared secret, wires the Git host, and proves each link works before you rely on push-driven refreshes instead of the three-minute poll.
Confirm the Argo CD endpoint is reachable from Git
Before touching the Git host, confirm that the Argo CD API server URL your Git provider will call is reachable from the provider's network. Your platform team decides whether that means a public ingress, an allowlisted address range, or a self-hosted Git server on the same network as Argo CD. Check the path from outside your cluster with a simple HTTPS request to the webhook endpoint, and confirm the TLS certificate chain is one the Git host trusts. Done means a request from a host on the Git provider's side reaches Argo CD and returns a response, not a timeout or certificate error.
Generate and store a strong shared secret
Generate a long random string with a cryptographic tool and store it in the Argo CD secret used for webhook validation, following the webhook configuration guide for the exact key names per provider. Keep the value out of Git, tickets and chat, and record which team owns it. Restrict who can read the Kubernetes secret with RBAC. Done means the secret exists in the Argo CD namespace, Argo CD has been restarted or reloaded as the guide requires, and the value is recorded only in your approved secret store.
Configure the webhook on the Git host
In the repository or organization settings of your Git host, add a webhook that points to the Argo CD endpoint, uses the same shared secret, and sends push events. Set the content type the provider and Argo CD guide specify. Limit scope to the repositories whose applications Argo CD tracks. Done means the webhook is saved and the provider shows it as active, with no pending configuration warnings.
Push a test commit and check the delivery log
Make a harmless commit to a branch that an Argo CD application tracks, such as a README change in a test repository. In the Git host's webhook delivery history, confirm that a delivery was recorded with a successful response code. A failed delivery with an authentication error usually means the secret does not match, and a failed delivery with a connection error points back to reachability. Done means the most recent delivery shows success for that push.
Confirm the refresh on the application
Open the tracked application in Argo CD and compare its last refresh timestamp with the time of the test push. A refresh that follows the push within moments, rather than waiting for the regular polling interval, confirms that the webhook reached Argo CD and triggered reconciliation. If the timestamp does not change, check the Argo CD API server logs for the webhook request and confirm the application's target revision matches the branch you pushed. Done means the timestamp moved after the push.
Verify a branch and a tag with the same name
Create a branch and a tag that share a name, for example release-1, and create an application that targets the tag using a fully qualified reference. Push a commit to the branch and check whether the tagged application refreshes. Argo CD does not distinguish branch and tag events with the same name, so a refresh here is the known gotcha and not a fault in your setup. Record the result, then decide on a naming rule that keeps branches and tags apart. Done means you have observed the behavior in your own environment and written the naming convention down.
Record the verified configuration and remove test artifacts
Document the endpoint, the secret owner and rotation location, the webhook settings on each provider, and the test results with timestamps. Delete the test commits, branches and tags, and confirm the applications return to their intended target revisions. Ask your Git host administrator to confirm which events are sent for each repository so that future changes do not silently remove push events. Done means the runbook names the owner for each part and the test repositories are back to their baseline state.
The branch and tag naming gotcha
Argo CD does not distinguish branch and tag events that share a name. A push to a branch called x can trigger a refresh of an application whose target revision is refs/tags/x, even though no tag changed. The refresh is harmless when Argo CD simply re-reads the tag and finds it unchanged, but it means a webhook can make an application look like it was updated when the release you care about has not moved. For teams that promote by tag, this blurs the link between a tag push and the deployment it is meant to drive, and it makes timing harder to reason about during an incident.
The practical control is naming discipline. Keep branch names and tag names in separate, non-overlapping patterns, for example release branches with a prefix such as release/ and release tags with a version format such as v followed by a semantic version. Then write the application target revision as a fully qualified ref (refs/tags/... or refs/heads/...) so the intent is explicit in the manifest. Your platform team should also confirm which naming rules your Git host and branch protection settings can enforce, because Argo CD itself will not reject a colliding name. Review these rules with the same people who own your release process, since they affect every application that targets a tag.
Before you rely on webhooks for tag-based releases, test the exact collision you are guarding against. Create a branch and a tag with the same name in a non-production repository, push each one, and observe which applications refresh and when, using the webhook delivery log on your Git host and the application events in Argo CD. Confirm that the tagged application still reports the revision you expect, and that polling still runs as a fallback if a delivery fails. Repeat the test for each Git provider you use, because webhook payloads and event types differ, and record the results in your change records as evidence for the release process.
Securing the webhook endpoint with shared secrets and network controls
A webhook endpoint that accepts unauthenticated requests can be used to trigger refreshes at will, so it needs the same care as any other inbound path into your delivery system. The cards below cover the secret, the network path, the payload checks and the logging that together keep the push path narrow and visible.
Strong per-provider shared secrets
Configure a separate, high-entropy shared secret for each Git provider that sends webhooks, and store it in a Kubernetes Secret rather than in a ConfigMap or in Git. Argo CD uses the secret to verify the signature on each delivery, so a request without a valid signature should be rejected. Confirm in the webhook configuration guide which signature header each provider uses, and set the same value on the provider side. Plan a rotation procedure that updates both ends in one change window, because a mismatch stops refreshes silently.
Restricting who reaches the endpoint
The webhook endpoint should be reachable only from the source addresses your Git provider publishes or from a controlled ingress path, not from the open internet by default. Decide whether the endpoint sits behind an ingress with an allowlist, a private network path to a self-hosted Git server, or both. Confirm with your provider whether it publishes source ranges for its hook deliveries, and document the list you enforce. Review the rules whenever the provider or your network changes.
Validating payloads against configured repositories
A valid signature proves who sent the request, not that the repository in the payload is one Argo CD should act on. Check that the repository URL in each delivery matches a repository registered in Argo CD, and that the branch or tag named in the payload corresponds to an application you expect to refresh. Ignore deliveries for unknown repositories instead of letting them trigger work. Test this with a delivery for an unregistered repository before go-live.
TLS on every webhook hop
Serve the webhook endpoint over TLS so the shared secret signature and payload cannot be read or altered in transit between the provider and your cluster. Use certificates issued by your internal or public certificate authority, renew them on a schedule, and confirm the provider trusts the chain it is given. If the Git host is self-managed, check that the certificate it presents is trusted by the webhook sender, not only by browsers.
Webhooks trigger refresh, not deployment
A webhook tells Argo CD to re-read Git and compare state. It does not grant anyone the right to change what runs in a cluster, and sync permissions still come from Argo CD projects and RBAC. Keep the webhook secret separate from any credential that can sync, and avoid giving the provider's hook identity access to the Argo CD API. Review the security documentation for the controls that govern deploy rights so that a leaked webhook secret cannot be turned into a deployment.
Audit logging of webhook deliveries
Record each webhook delivery that Argo CD accepts or rejects, including the provider, repository, time and outcome, and forward those records to your central log store. Rejected deliveries are often the first sign of a misconfigured secret or an unexpected sender. Set alerts on bursts of rejected requests and review the trend after any secret rotation. Confirm which fields your Argo CD version writes to its logs before you build the dashboard.
Questions teams ask before changing Argo CD refresh behavior
Do webhooks replace polling in Argo CD entirely?
No. Webhooks remove the default three-minute delay for applications whose Git provider sends a push notification, but Argo CD still polls repositories on its normal schedule. Polling stays as a safety net for events that never arrive, for repositories whose provider is not supported, and for changes that bypass the push path. Plan to keep the polling interval in place and treat the webhook as the fast path. Confirm how your Argo CD version handles the interval in its webhook guide before you reduce any timer.
How long does webhook setup take, and what drives that time?
The duration depends on the number of Git providers, the number of repositories and the network path between each host and Argo CD. Each provider needs its own webhook entry, a shared secret, and a verified delivery test. Teams with one provider and a few repositories usually finish in a short working session, while multi-provider estates need more coordination with Git administrators and firewall owners. Ask any partner for a written schedule tied to the repository list, and confirm the provider list against the supported providers in the Argo CD webhook guide.
Can an internal team set up Argo CD webhooks without a partner?
Yes, if the team has someone who administers the Git host, someone who operates Argo CD, and time to test each path. The configuration itself is small: a shared secret in a Kubernetes Secret and a webhook URL pointing at the Argo CD API server. The harder parts are secret rotation, ingress exposure of the webhook endpoint, and confirming that the branch and tag rules match your naming. A partner adds value when many repositories or several providers must be covered consistently and documented for audit.
What does the work need from Git host administrators and Argo CD operators?
Git host administrators must create the webhook on each repository or organization, set the content type and the shared secret, and allow Argo CD's endpoint to receive deliveries. Argo CD operators must expose the webhook path through ingress or a load balancer, store the secret where the API server reads it, and check that deliveries are accepted. Both groups should agree on who rotates the secret and how failed deliveries are investigated. Write this split down before the change window opens.
What changes for monorepos when webhooks are enabled?
A push to a large monorepo can trigger refresh for every application that tracks it, which makes webhook scope a performance question as well as a speed question. Teams usually combine webhooks with path-based refresh annotations and fully qualified target revisions so that only affected applications regenerate manifests. Test the event volume on a copy of the largest repository before enabling it everywhere. Confirm the exact annotation behavior for your Argo CD version in its documentation.
Does the branch and tag naming rule affect webhook results?
Yes. Argo CD does not distinguish a branch and a tag that share a name, so a push to a branch called x can refresh an application that targets the tag refs/tags/x. Audit your repository for matching names before you rely on webhook-triggered refresh, and prefer fully qualified target revisions in application manifests. A naming convention for release tags, enforced in the Git host, prevents most surprises.
What does a fixed-scope engagement cover for webhook work?
A fixed-scope engagement covers the agreed set of providers, repositories, Argo CD instances and test evidence named in the written scope, along with the deliverables and timeline agreed before work starts. Typical items include webhook configuration per provider, shared secret handling, payload size and endpoint checks, refresh jitter settings, naming audit and a runbook. Anything outside that list, such as new providers or a wider repository estate, is quoted separately. Ask for the scope in writing, and DeployOpen will price it from that document.
Pairing webhooks with monorepo performance and refresh jitter
A webhook removes the three-minute polling delay for an application, but it does not decide how much work Argo CD does when a push arrives. In a large monorepo, one commit can point at many applications, and if each of them refreshes at once, the repo-server and the application controller absorb a spike that polling would have spread out. Treat webhooks as the trigger and plan the rest of the refresh behavior alongside them. The three controls that matter most are the argocd.argoproj.io/manifest-generate-paths annotation, fully qualified target revisions, and refresh jitter, which is the randomized delay Argo CD applies to scheduled refreshes so applications do not all refresh on the same tick.
Each of these controls answers a different question. The manifest-generate-paths annotation limits which application refreshes a push can trigger, so a commit that touches only one service does not regenerate manifests for the whole repository. Fully qualified target revisions, such as refs/heads/main instead of main, remove ambiguity about which ref an application tracks, which also matters for the branch and tag naming behavior described earlier on this page. Jitter spreads the scheduled refreshes that still occur. Before you enable webhooks on a busy repository, ask your team to list which applications share each path, and confirm with your Argo CD version's documentation how jitter is configured, since the setting names and defaults should be checked against the release you run.
These sibling topics go deeper than this page and should be read together with it for tuning. The Argo CD high availability documentation explains the component layout that absorbs refresh load, and the monorepo performance topic in this group covers the annotation, revision and clone trade-offs in detail. This page stays on webhook setup, secrets and payload handling. If a push still causes a refresh storm after these controls are in place, troubleshoot the repo-server and controller before adding more webhook endpoints.
How DeployOpen scopes and delivers webhook changes
Webhook changes touch your Argo CD installation, your Git hosts and your change process at the same time, so the work is agreed in writing before anything is configured. DeployOpen then makes each change inside your own infrastructure and hands over what your operators need to run it.
Written scope before work starts
The scope lists which Git providers send webhooks, which Argo CD applications move from polling to push, and which branch and tag patterns are in play. It also names who approves changes to Git host settings and secrets. Ask for the scope to state whether the work covers one Argo CD instance or several, since each instance needs its own endpoint and secret.
Configuration in your own environment
DeployOpen configures the webhook receiver, the endpoint exposure and the shared secrets inside your cluster and on your Git hosts, using your accounts and access controls. Secrets are created in your secret store rather than pasted into chat or tickets. Confirm which team holds the Git host admin role so changes are made by people who can later revoke them.
Verification with test pushes
Each provider is tested with real pushes to a non-production branch, plus a tag push that shares a name with a branch. The test confirms that the right application refreshed, that rejected payloads are logged, and that unauthenticated requests fail. Ask for the test log and the list of applications verified, so you can repeat the checks after upgrades.
Naming rules and documentation
DeployOpen documents the branch and tag naming rules your teams must follow, the refresh jitter settings and the payload limits. It also records which applications still rely on polling as a fallback. Handover covers how to rotate a shared secret, how to add a new repository and what to check when a push does not trigger a refresh.
Handover to your operators
A working session walks your platform and security engineers through the configuration, the failure signs and the rollback steps. Your operators keep ownership of the cluster, the Git hosts and the secrets after the engagement closes. Confirm that the handover includes access to the runbook and the names of the people who will maintain the webhook settings.
Ongoing support and testing retainers
Webhook settings can break after Argo CD upgrades, Git host changes or secret rotation, so some teams keep DeployOpen on a retainer for regular checks. A retainer covers re-testing after upgrades and reviews of the webhook configuration. DeployOpen does not publish a price list, so ask for a quote based on your written scope and the check frequency you need.
