What Is a Webhook? How It Works, Webhook vs API, and Real Examples

A webhook is a way for one system to automatically send data to another when a specific event happens. Instead of checking repeatedly to see whether anything changed, the receiving system gets notified right away.

That sounds simple, and it is. But the part most explainers skip is this: getting a webhook delivery is only the beginning. The hard part is turning that incoming event into something reliable, secure, and actually useful for a team. This guide covers both sides, what a webhook is, and what usually goes wrong in real webhook-driven workflows.

What is a webhook?

A webhook is an automatic HTTP request sent from one application to another when a defined event occurs.

The sending system watches for an event, such as a payment succeeding, a form being submitted, or a pull request being opened. The receiving system exposes a URL, usually called a webhook endpoint. When the event happens, the sender delivers a payload to that endpoint, and the receiver processes it.

A few common examples:

- Stripe sends a webhook when a payment succeeds or fails.

- GitHub sends a webhook when code is pushed or a pull request changes state.

- Twilio sends a webhook when an SMS arrives or a phone call comes in.

- PayPal sends a webhook when a refund is initiated or a subscription renews.

If you want the shortest possible definition, it is this: a webhook is event-driven data delivery over HTTP.

How does a webhook work?

At a high level, the flow looks like this:

1. Something happens in the source system.

2. The source system creates a payload with event details.

3. It sends an HTTP request to your webhook URL.

4. Your application validates the request.

5. Your application decides what to do next.

Usually, the payload is JSON. It often contains an event type, a timestamp, an object ID, and the fields relevant to the change.

For example, a payment webhook might include a payment ID, amount, status, and customer reference. A GitHub webhook might include the repository, branch, commit metadata, and event action.

Webhook vs API

This is the most common source of confusion.

An API is something you call when you want data or want to trigger an action.

A webhook is something that calls you when an event happens.

That is the simplest way to remember the difference: you call an API, a webhook calls you.

In practice, APIs and webhooks often work together. A webhook tells your system that something changed. Then your application may call the API to fetch the latest, authoritative version of the record before taking action.

This matters because webhook payloads are often good enough to trigger a workflow, but not always ideal as the only source of truth.

Webhook vs polling

Polling means checking for updates on a schedule.

Imagine asking a payment provider every 30 seconds whether a payment has cleared. Or asking a shipping system every minute whether an order status changed. That is polling.

A webhook flips that model. Instead of asking again and again, your system gets notified when the event actually happens.

Why teams prefer webhooks when available:

- fewer unnecessary requests

- faster updates

- better scalability across many events and systems

- less wasted infrastructure and API quota

Polling still has its place. If a service does not support webhooks, polling may be your only option. It can also be fine when near real-time updates are not important. But when the business process depends on reacting quickly, webhooks are usually the better fit.

Common webhook examples

The easiest way to understand webhooks is through real workflows.

Payments

A provider such as Stripe or PayPal can send a webhook when a payment succeeds, fails, or is refunded. Your system can then update an order, trigger fulfillment, notify finance, or flag an exception.

Code and deployment

GitHub can send a webhook when a push happens, a pull request is opened, or a release is published. Teams use these events to trigger CI, deployments, notifications, and audit trails.

Messaging and communications

Twilio can send a webhook when an inbound SMS arrives or a phone call starts. Your application can route the interaction, create a ticket, or kick off a workflow.

Forms and lead capture

A form tool can send a webhook when someone submits a contact or intake form. That event can create a CRM record, notify sales, or start onboarding.

CRM and support changes

A CRM can send a webhook when a lead changes stage or an account owner is reassigned. A support platform can send one when a high-priority case is opened.

What does a webhook payload contain?

A webhook payload contains the information the receiving system needs to understand the event.

That usually includes:

- the event type

- when the event happened

- the ID of the object that changed

- relevant changed fields or statuses

- metadata about the request or source system

The exact structure varies by provider. A Stripe event does not look like a GitHub event, and a Twilio event does not look like a CRM event. That is why implementation always starts with the provider’s docs, not with assumptions.

What a webhook endpoint needs

A lot of introductory content makes webhook setup sound like “just add a URL.” In reality, a production-ready webhook endpoint needs a bit more care.

A public HTTPS endpoint

Most webhook providers require a publicly reachable HTTPS URL. Stripe requires registered webhook endpoints to use publicly accessible HTTPS URLs, and PayPal describes webhooks as HTTPS posts to an endpoint on your server. Twilio is also tightening its HTTPS requirements across webhook-related traffic in 2026.

Request validation

You should verify that the request really came from the provider you expect.

- Stripe recommends verifying webhook signatures with the `Stripe-Signature` header.

- GitHub recommends using a webhook secret.

- Twilio signs requests using the `X-Twilio-Signature` header.

If you skip validation, your endpoint is just a public URL that anyone can hit with fake event data.

Fast responses

Webhook providers generally expect a quick 2xx response.

GitHub explicitly says your server should respond within 10 seconds, otherwise the delivery is treated as failed. Stripe’s support guidance also emphasizes that your server should promptly return a 200-299 status to confirm receipt.

That usually means one thing: acknowledge fast, then do the heavier processing in the background.

Structured processing logic

Your system needs to know what to do with each event type. That includes mapping payloads to business actions, ignoring events you do not care about, and handling state changes safely.

Logging and replay visibility

If webhook processing breaks and you have no delivery logs, no event IDs, and no replay path, debugging becomes painful very quickly. This is one of the most common practical failures in webhook-based systems.

The real problems teams hit with webhooks

This is the part most “what is a webhook” articles underplay. In production, teams usually struggle less with the concept and more with the failure modes.

1. Signature verification fails even when the endpoint “works”

This is especially common with Stripe.

Stripe’s docs note that webhook signature verification requires the raw request body. If your framework parses or mutates that body before verification, signature checks fail even though the route itself seems fine.

This is a very current problem because many modern stacks, especially serverless and framework-heavy ones, transform request bodies by default. The endpoint may look healthy, but the verification logic quietly breaks.

Practical takeaway: treat raw-body handling as part of the webhook contract, not as an implementation detail.

2. Teams do too much work before replying

A common anti-pattern is receiving the webhook and then doing all the real work synchronously: database writes, third-party API calls, enrichment, notifications, and UI updates before sending a response.

That makes timeouts and retries more likely.

GitHub recommends responding quickly and moving work to a queue. This is good webhook architecture in general: receive, validate, persist, acknowledge, then process asynchronously.

3. Duplicate deliveries are not handled

Webhook endpoints should expect duplicates.

Stripe’s docs explicitly warn that endpoints may occasionally receive the same event more than once. GitHub recommends using delivery identifiers such as `X-GitHub-Delivery` to track uniqueness and defend against replay-related issues.

If your handler is not idempotent, duplicate deliveries can create duplicate orders, duplicate notifications, duplicate tickets, or inconsistent state.

A practical rule: every important webhook workflow should have a deduplication strategy.

4. Teams trust the webhook payload too much

A webhook is often best treated as the signal that something happened, not always as the final record.

For example, if a payment or account object can change again after the event was generated, it may be safer to fetch the latest object via API before taking irreversible action. This pattern is especially useful in finance, subscriptions, and operational workflows where stale data creates business risk.

A good webhook handler often does this:

- verify the event

- store the event ID

- inspect the event type

- fetch or reconcile fresh data if needed

- execute the business action

5. Teams subscribe to too many events

GitHub explicitly recommends subscribing only to the minimum number of events you need. This is a useful rule everywhere.

If you subscribe to everything, you increase noise, processing cost, storage volume, and debugging complexity. You also make it easier to miss the events that actually matter.

A leaner event subscription model usually produces better systems.

6. Nobody plans for missed deliveries

Servers go down. Deployments break routes. Secrets rotate. Firewalls block requests. Providers retry, but retries are not magic.

GitHub’s best practices explicitly mention redelivering missed webhooks after downtime. In other words, reliable webhook systems need a recovery path, not just a happy path.

If your business process is important, you should know:

- how to see failed deliveries

- how to replay them

- how to confirm whether they were already processed

- how to recover after downtime

7. Webhook events arrive, but the team still cannot act on them

This is the most underrated problem.

A webhook can successfully hit your backend, update a database row, and still fail from a business point of view because nobody has a usable interface to see, review, approve, or fix what happened.

For example:

- A payment provider sends a failed-payment event.

- A CRM sends a lead-stage-change event.

- A support tool sends an urgent-case event.

The webhook delivery works. But then what?

If the team has no queue, no dashboard, no review screen, no audit trail, and no permissions layer, the event becomes “data somewhere,” not an operational workflow.

That is the gap many teams discover after they “finish” the integration.

Are webhooks secure?

They can be, but only if you implement them properly.

At a minimum:

- use HTTPS

- verify signatures or webhook secrets

- avoid exposing sensitive data in the payload URL

- validate event type and payload structure

- log suspicious failures

- design for replay and duplicate handling

GitHub recommends using a webhook secret and keeping sensitive data out of the payload URL. Twilio provides request validation through its SDKs and documents how signatures are calculated. Stripe recommends signature verification through its official libraries and makes raw-body handling part of that process.

Security is only part of the story, though. Reliability matters just as much. A secure endpoint that silently loses important events is still a bad integration.

When a webhook alone is not enough

A webhook is very good at one thing: telling a system that something happened.

But business teams often need more than a notification.

They may need:

- an exception queue for failed payments or sync errors

- an approval flow before a refund or update is finalized

- a dashboard that combines incoming events with API and database data

- a support workspace where agents can investigate the event in context

- an internal audit trail for what happened next

This is where a tool like UI Bakery fits naturally.

If a team already has APIs, databases, and incoming webhook-driven events, UI Bakery can help turn that event stream into something operational: an internal dashboard, admin panel, approval workflow, review queue, or back-office app. In that setup, the webhook delivers the signal, and the internal tool gives people a practical way to work with it.

That is a more useful way to think about webhooks in business systems. Not as isolated HTTP requests, but as the triggers that feed real internal workflows.

Conclusion

A webhook is a simple way for one system to notify another when something happens. That is the easy part.

The harder and more valuable part is building a system that can validate those events, process them safely, recover from failures, and turn them into workflows people can actually use.

That is why the best webhook setups are not just about receiving payloads. They are about reliability, visibility, and action. The event arrives, the system reacts, and the team has a usable way to handle what comes next.