What Is a Webhook and How Does It Work

If APIs are the general plumbing of workflow automation, webhooks are one of the most important patterns that plumbing enables.

They solve a very specific problem:

How does one system tell another system that something just happened, without making the other system keep asking?

That is why webhook knowledge matters so much in automation work.

Without webhooks, teams often end up polling APIs over and over:

• "Has a new order arrived yet?"
• "Did the ticket status change yet?"
• "Was the payment completed yet?"
• "Did someone push code yet?"

That can work, but it is wasteful and often slower than it needs to be.

Webhooks change the model.

Instead of constantly checking, your system subscribes to an event and waits to be told when it happens.

That sounds simple, but there is a lot of operational detail hiding underneath it.

The simplest webhook definition

GitHub's documentation gives one of the clearest practical definitions:

webhooks let you subscribe to events happening in a software system and automatically receive a delivery of data whenever those events occur.

That is the right mental model.

A webhook is not just "an API thing."

It is an event-delivery mechanism.

The source system notices an event, then sends an HTTP request with event data to a URL you control.

That URL is often called:

• a webhook endpoint
• a receiver
• a listener
• a callback URL

How a webhook works

At a high level, a webhook flow looks like this:

1. You register interest in an event

Examples:

• order paid
• form submitted
• customer updated
• issue created
• repository pushed

2. You provide a destination URL

This is the endpoint where the source system will send the delivery.

3. The source system watches for the event

When the event occurs, it packages up information about that event.

4. The source system sends an HTTP request

Usually this is a POST request containing a JSON payload.

5. Your receiving system validates and processes it

That may include:

• checking the signature or secret
• reading the event type
• deciding whether to ignore or handle it
• triggering downstream steps

6. Your workflow takes the next action

Examples:

• create or update a record
• notify a team
• start another automation
• fetch more data from an API
• queue background processing

That is the full idea.

Webhooks vs polling

This is the most important comparison to understand.

GitHub explicitly contrasts webhooks with polling: webhooks deliver data when something happens, while polling means calling an API repeatedly to see whether new data is available.

That difference affects:

• efficiency
• speed
• scale
• platform design

Polling

Polling means your system keeps asking:

• "Anything new?"
• "Anything changed?"
• "Any updates yet?"

It can be useful when:

• the source system has no webhook support
• you need periodic syncs anyway
• you are backfilling or reconciling data

But polling can also:

• waste requests
• hit rate limits
• create delays between event and action
• force you to manage schedules and intervals

Webhooks

Webhooks mean the source system pushes the event to you.

That usually gives you:

• fewer unnecessary requests
• faster response times
• more natural event-driven workflows

But it also means your receiving system needs to be ready when the event arrives.

That is the tradeoff.

What webhook payloads usually contain

A webhook delivery normally includes:

• the event type
• a payload body with event data
• headers with metadata
• sometimes a signature or delivery ID

The exact shape depends on the platform, but the pattern is consistent.

For example, GitHub recommends checking the event type and action before processing a payload. It also documents the X-GitHub-Delivery header for uniquely identifying deliveries.

Those details matter because not every webhook should trigger the same downstream work.

Webhooks and APIs usually work together

A common beginner misunderstanding is to think you must choose between APIs and webhooks.

In practice, strong workflows usually use both.

A webhook tells you that something happened. An API often helps you decide what to do next.

For example:

1. A payment platform sends a webhook that a payment succeeded.
2. Your system validates the webhook.
3. Your workflow calls the platform API to retrieve full transaction details.
4. Your workflow updates the CRM, order system, and reporting tools.

The webhook is the event trigger. The API is the action and data layer.

That is why this lesson follows APIs for Workflow Automation Explained.

Common webhook use cases

Webhooks appear everywhere once you know what to look for.

Software and product workflows

• code pushed
• pull request opened
• deployment completed
• incident created

Ecommerce workflows

• order placed
• payment succeeded
• refund created
• shipment updated

CRM and sales workflows

• lead created
• deal stage changed
• form submitted
• meeting booked

Support workflows

• new ticket created
• priority changed
• conversation assigned
• SLA breached

Internal operations workflows

• spreadsheet row added
• document signed
• approval completed
• HR record updated

The event changes, but the delivery pattern stays the same.

What makes webhook-based automation reliable

This is where teams often get sloppy.

They create a webhook endpoint, test one happy-path delivery, and assume the job is done.

Production webhooks need more discipline than that.

GitHub's best-practices page is useful because it captures the operational basics clearly.

1. Subscribe only to the events you need

More events means more noise, more load, and more chances to mis-handle something irrelevant.

2. Use a webhook secret

GitHub explicitly warns against putting secrets in the payload URL and recommends validating deliveries with a webhook secret instead.

That principle applies broadly:

• verify who sent the event
• do not trust raw inbound requests
• validate before processing

3. Use HTTPS

Webhook endpoints should use HTTPS, not plain HTTP.

That is basic transport hygiene.

4. Respond quickly

GitHub recommends responding with a 2XX within 10 seconds and pushing longer work into background processing.

That is excellent general webhook advice.

Do this instead of:

• validating slowly
• running heavy downstream work inline
• making the sender wait while your entire automation completes

The healthier pattern is:

1. receive
2. validate
3. acknowledge quickly
4. queue the work
5. process in the background

5. Check event type and action

Do not assume every delivery deserves the same handling.

Some event families contain multiple actions, subtypes, or irrelevant updates.

6. Track delivery IDs and retries

GitHub recommends using delivery identifiers and redelivering failed events when needed.

That points to a broader production truth:

• deliveries can fail
• retries can happen
• duplicates can happen
• downstream systems can be temporarily unavailable

Good webhook handlers are written with that in mind.

Common webhook mistakes

The most common production mistakes are not conceptual. They are operational.

Mistake 1: Treating the webhook URL as enough security

A webhook endpoint without verification is just a public URL waiting to be abused.

Mistake 2: Doing too much work before acknowledging

If your receiver blocks on slow processing, you increase failure risk immediately.

Mistake 3: Ignoring duplicate or replay scenarios

If the same event arrives twice, can your system handle it safely?

If not, the workflow is fragile.

Mistake 4: Subscribing to too many events

This creates noise and raises the chance of misfires.

Mistake 5: Building no observability

If you cannot answer:

• what was delivered
• what failed
• what was retried
• what was ignored

then the workflow is not ready for real operational use.

When webhooks are the wrong tool

Webhooks are powerful, but they are not always the answer.

Polling can still be the better fit when:

• the provider has no webhook support
• you need periodic reconciliation
• you need to compare full datasets on a schedule
• you are working with systems that cannot expose reliable inbound endpoints

The best automation programs usually combine both:

• webhooks for event-driven speed
• polling or scheduled jobs for reconciliation and backfill

So what is a webhook, really?

A webhook is the event subscription layer of modern workflow automation.

It lets systems say:

"You do not need to keep asking. I will tell you when it happens."

That is what makes webhooks so useful.

They reduce waste, speed up handoffs, and create more natural event-driven workflows.

But a webhook is not just a URL and a payload.

A production-ready webhook setup also needs:

• validation
• filtering
• fast acknowledgement
• background processing
• retry awareness
• delivery tracking

If you understand those pieces, you will build much safer automations than teams that treat webhooks as simple glue.

From here, the cluster can go in two directions:

• deeper into request-response concepts
• deeper into event-driven patterns like polling, retries, idempotency, and integration reliability

Either way, webhook literacy is one of the clearest signals that a workflow automation program is maturing beyond "just connect the apps."