Let’s build a clear mental model before adding any technical vocabulary.

A webhook is a way for GitHub to automatically notify another system the moment something specific happens in a repository or organization — a new commit being pushed, a pull request being opened, an issue being commented on, and dozens of other possible events. Rather than that other system repeatedly checking in and asking whether anything new has occurred, GitHub sends the information directly, on its own initiative, the instant the relevant event actually takes place.

Technically, setting up a webhook means telling GitHub a specific web address — an endpoint belonging to some other system — and which events you want GitHub to report to it. From that point forward, whenever a matching event happens, GitHub packages up details about it and delivers them straight to that address, essentially placing an automatic, near-instant phone call to whoever is listening there.

With that foundational picture in place, let’s define the vocabulary that makes up a webhook’s actual structure.

A handful of terms make the entire webhook system click into place.

With this vocabulary settled, let’s trace exactly what happens internally the moment a webhook-triggering event occurs.

This is the heart of the topic — the journey from a real happening on GitHub to a notification landing on someone else’s system.

sequenceDiagram
    participant Repo as Repository
    participant GitHub as GitHub
    participant Endpoint as Receiving System
    Repo->>GitHub: Event occurs (e.g. new pull request)
    GitHub->>GitHub: Build and sign payload
    GitHub->>Endpoint: Deliver payload to configured endpoint
    Endpoint->>GitHub: Send back confirmation response
        

Zooming out from a single delivery, let’s see how webhooks fit into the broader flow of connected systems.

A single repository can have several webhooks configured simultaneously, each pointed at a different external system and often watching for different sets of events. One webhook might notify a chat tool whenever someone opens an issue, another might trigger a build pipeline whenever code is pushed, and another might update an external project-tracking tool whenever a pull request is merged. Together, these independent notifications let GitHub sit at the center of a much larger, interconnected ecosystem of tools.

flowchart LR
    A[Event happens in repository] --> B{Which webhooks are watching?}
    B --> C[Webhook 1: Chat notification tool]
    B --> D[Webhook 2: External build pipeline]
    B --> E[Webhook 3: Project tracking tool]
    C --> F[Team notified instantly]
    D --> G[Build begins automatically]
    E --> H[Tracking tool updates status]
        

This fan-out pattern is one of webhooks’ greatest strengths: a single, real event can ripple outward to power several entirely independent automated reactions, without those reactions needing to know about each other at all. Each receiving system simply reacts to its own copy of the notification, entirely on its own terms.

Before webhooks, the common alternative was repeatedly asking a system whether anything new had happened. Comparing the two makes the benefit obvious.

GitHub supports a genuinely wide range of event types, reflecting nearly every meaningful action that can happen in a repository.

The payload is where the real substance of a webhook lives — let’s look at what it typically contains.

Every payload includes details specific to the type of event that triggered it, along with broader context about where that event happened, such as which repository and which user was involved. A push event’s payload, for instance, includes information about the commits involved, while an issue event’s payload includes details about the issue’s title, description, and current state.

Both webhooks and automated workflow files react to repository events, which naturally raises the question of how they actually relate.

Sending a notification is one thing — making sure it’s actually received is another. GitHub builds in some reliability handling worth understanding.

Webhooks aren’t a silent, invisible process — GitHub provides real visibility into exactly what’s been sent and how it went.

Webhooks bring genuine, meaningful benefits over older approaches, alongside a few real responsibilities that come with them.

Because a webhook endpoint is a publicly reachable address, a handful of genuine security considerations deserve real attention.

A few recurring habits separate teams that build reliable webhook integrations from teams that quietly accumulate fragile ones.

A concise set of habits keeps a webhook integration reliable, secure, and easy to maintain over time.

Webhooks aren’t a niche capability — they quietly power a huge share of the integrations developers rely on every day.

Yes, generally the endpoint needs to be reachable and ready to receive deliveries whenever an event might occur, since GitHub sends the notification proactively rather than waiting for the system to ask.

The delivery attempt will be recorded as failed, and depending on configuration, it may be possible to manually resend that specific delivery once the endpoint is available again.

Yes, a single webhook configuration can typically subscribe to multiple event types simultaneously, all delivered to the same endpoint.

No, relying purely on obscurity is not a genuine security measure. Verifying the payload’s signature against the configured secret is the reliable way to confirm authenticity.

No — as covered earlier, workflow triggers run automation directly within GitHub’s own infrastructure, while webhooks notify entirely external systems that you build and host yourself.

A webhook is GitHub’s way of proactively notifying an external system the moment a specific event happens, replacing wasteful, repeated checking with instant, direct delivery. Built from events, payloads, endpoints, and secure signatures, webhooks let a single real happening ripple outward to power chat notifications, external build systems, and custom integrations, all independently and simultaneously. Used well — with careful event selection, robust signature verification, and graceful handling of retries — webhooks become a reliable, foundational bridge connecting GitHub to the much larger ecosystem of tools a team actually relies on.