What is a webhook?

A webhook flow is straightforward:

• An event happens in the source system, such as a code push, comment, merge request, or deployment change.
• The source system packages event details into a payload, often JSON.
• It sends that payload as an HTTP POST request to a webhook endpoint URL.
• The receiving system validates the request and takes action, such as sending a notification or triggering automation.

Because data is sent when the event occurs, webhooks help teams build faster, event-driven workflows across modern DevOps toolchains.

Webhooks and APIs work together, but they are not the same thing. APIs let applications request data when needed, while webhooks send data automatically when a specific event happens.

The difference often comes down to polling versus pushing:

• Polling means a client keeps asking an API whether something changed.
• A webhook means the source system pushes the payload immediately after the event occurs.

That push model reduces unnecessary requests and helps downstream systems respond faster.

Teams use webhooks to keep systems synchronized without manual handoffs or constant checks for updates. In GitLab, webhooks connect GitLab to other tools and systems through real-time notifications so teams can react to changes as they happen.

Common benefits:

• Faster updates between systems because data is sent when the event occurs
• Less overhead than repeated polling
• Easier automation for software delivery workflows such as notifications, issue updates, and CI/CD deployments

Webhooks are commonly used for:

• Updating external issue trackers when project activity changes
• Notifying chat tools when pipelines complete
• Triggering scripts or jobs when code reaches an important branch
• Sending event data to downstream systems for monitoring or automation

They are especially useful in GitOps workflows, where repository changes can act as the signal for downstream infrastructure or operational automation.

A webhook payload contains details about the event that triggered the request. The exact fields depend on the application and event type, but webhook payloads are commonly sent in formats such as JSON so receiving systems can process them programmatically.

In GitLab, webhook payloads can represent many kinds of project or group events, and GitLab supports custom webhook templates so teams can control the JSON body sent to their endpoints.

Because webhooks connect systems automatically, the receiver should validate both the sender and the transport.

Common practices:

• Using HTTPS to protect data in transit
• Validating requests with a secret or token
• Using mutual TLS in environments that require stronger authentication
• Designing the receiver to be fast and stable so event handling stays reliable

GitLab sends the secret token in the X-Gitlab-Token HTTP header so the receiving endpoint can verify the request.

GitLab webhooks can react to many project and group events, including:

• Pushing code to a repository
• Posting a comment on an issue
• Creating a merge request
• Deployment activity

GitLab also supports filtering, templates, custom headers, and request history, which gives teams more control over how webhook-based integrations behave in production. Teams setting up those flows can also review the GitLab Docs page on webhooks.

A webhook is a simple pattern with a big payoff: When something important happens, the right system is notified immediately and can respond on its own. For teams using GitLab, webhooks connect project events to external tools, automation, and operational workflows without adding manual steps. Teams exploring broader automation patterns can also learn how GitLab approaches infrastructure automation.