What Is a Webhook? How Event-Driven Integrations Work

Webhook is a mechanism that enables one system to automatically notify another about an event as soon as it occurs. Instead of constantly polling a server, an application receives data at the exact moment it becomes available-such as after a successful payment, a new order, or a change in delivery status.

Webhooks are especially valuable for integrating multiple services. They reduce unnecessary requests and allow faster reactions to changes. While webhooks are closely related to a traditional API, they operate on a different principle.

What Is a Webhook and Why Are They Needed?

Webhooks in Simple Terms

The simplest way to understand the difference between an API and a webhook is through the analogy of notifications.

With a standard API, your application repeatedly asks another server, "Are there any new updates?" If nothing has changed, it keeps making the same request at intervals.

A webhook works the other way around. The application provides a special address to the service, and the service itself sends a request there when the relevant event occurs.

For example, an online store doesn't need to ask its payment system every few seconds if an order has been paid. The payment service can send a webhook immediately after payment confirmation.

This is why webhooks are often called notification mechanisms between applications. Instead of constantly polling another system, you simply wait for a message about the event.

What Problems Do Webhooks Solve?

Webhooks are used when a system needs to respond quickly to changes in another service. Typical examples include:

• a payment system notifying a store about a successful payment;
• a CRM receiving a new inquiry from a website;
• a delivery service updating the status of an order;
• a Git platform triggering a build after new code is pushed;
• a messenger delivering a new message to a bot;
• a cloud service reporting that file processing is complete.

The main feature of these scenarios is that actions are event-driven. The system doesn't check status at regular intervals-it receives a signal only when something actually happens.

This principle is used not only in small integrations but also in large-scale software systems. Learn more in the article Why event-driven architecture makes systems faster and more responsive.

Thanks to this, webhooks are especially handy for automation. After receiving an event, a program can automatically change an order status, notify a user, write data to a database, or trigger another process.

How Does a Webhook Work?

Event, URL, and HTTP Request

To use a webhook, the receiving system first creates a special URL-called an endpoint. This is the address where another service will send notifications about events.

The process is straightforward:

1. An event occurs
2. The service formats the data
3. It sends an HTTP request
4. The receiving system processes the information

For example, when a user makes a payment, the payment service records the transaction and sends an HTTP request to the store's webhook URL. The store receives the request, updates the order status to "Paid," and can trigger further actions automatically.

Most webhooks use the HTTP POST method, since event data is sent with the request. However, the exact format depends on the service-some platforms may use other HTTP methods.

What's Inside a Webhook Request?

A typical webhook request includes several parts. The URL specifies the handler's address, HTTP headers may carry service data, and the main event information is in the request body.

Many services use the JSON format to transfer data. For example, a payment notification might include an order ID, amount, currency, payment status, and timestamp.

Simplified, such data could look like:

{
  "event": "payment.success",
  "order_id": "A1024",
  "status": "paid"
}

Upon receiving such a request, the application reads the event field, determines the event type, and starts the corresponding logic. If the event is about payment, the order is marked as paid; if it's a delivery update, the order status is changed.

After processing, the webhook server usually returns an HTTP response code. A code in the 200 range means the request was received successfully. If the server returns an error or doesn't respond, the sending service may try to deliver the event again.

Webhook Workflow Example

Imagine an online store connected to an external payment system.

The customer places an order and proceeds to the payment page. After the payment, the payment service receives confirmation from the bank. At this point, the store may still be unaware of the payment result.

Instead of the store repeatedly checking the payment status via API, the payment system sends a webhook:

payment.success → store's webhook → updates order status

The store's server receives the notification, verifies the data, and automatically changes the order status to "Paid." The system can then send a receipt, notify the warehouse, and begin preparing the order for shipment.

This approach is especially useful for processes where an event might happen seconds, minutes, or even hours after the initial request. The application doesn't need to keep checking the status-it simply waits for the webhook.

Webhook vs. API: What's the Difference?

API Is Request-Based, Webhook Is Event-Based

The key difference between a webhook and a traditional API lies in who initiates data exchange.

With an API, the application sends requests to the server. For example, it might ask for an order list, user profile, or payment status. The server only responds after receiving such a request.

Webhooks operate differently. The recipient provides a URL in advance, and the source service sends a request when the relevant event occurs.

You can think of two models:

• API: "Ask if something happened."
• Webhook: "Get a message when something happens."

In technical documentation, these are often called pull (API) and push (webhook) models. APIs are used for pull mechanisms, where the client fetches data, while webhooks use push mechanisms, with data sent automatically to the recipient.

Webhook vs. REST API

Both webhooks and REST APIs use the same basic internet technologies-HTTP, URLs, headers, request methods, and formats like JSON. Their purposes, however, are different.

For instance, an API lets a store query details about a specific payment. With a webhook, the payment system itself notifies the store when a payment succeeds.

So, it's not quite correct to view webhooks and APIs as mutually exclusive technologies.

Webhooks Don't Replace APIs

In practice, webhooks and APIs usually work together.

Use the API when your program needs to fetch or modify data. Webhooks are used to learn about events as soon as they occur.

For example, in a CRM system, the API retrieves a customer's profile, changes a phone number, or requests order history. A webhook can notify an external system when a new client appears or a deal stage changes.

Sometimes, a webhook sends only minimal information-such as an object ID and event type. The application then calls the API for full details.

This approach avoids constant polling while keeping the flexibility of a traditional API.

When to Use Webhooks and When to Use APIs

When Are Webhooks Better?

Webhooks are ideal when your system needs to know about an event as soon as it happens.

Common examples: payment confirmation, new order creation, delivery status updates, new CRM leads, file uploads, or code published to a repository.

In these scenarios, frequent API requests create unnecessary load. If your application checks order status every minute, most requests may return the same result. Webhooks eliminate this redundancy-requests are sent only when something changes for real.

This makes webhooks especially useful for automating processes and integrating services that must react almost instantly to events.

When Are APIs More Appropriate?

Standard APIs remain preferable when your application needs to obtain data at any time.

For instance, when a user opens an online store page and wants to see their orders, the application sends an API request for the current list.

APIs are also needed when the system must:

• perform searches,
• retrieve lists of objects,
• create or update records,
• delete data,
• request detailed info by ID,
• choose when to contact the server.

Webhooks aren't designed for these tasks-they notify about events, but don't allow you to request arbitrary information on demand.

A common pattern is using a webhook to signal that something changed, after which the application fetches the required data via API.

Webhooks, Polling, and WebSocket

Webhooks aren't the only way to receive updates from another service. Depending on the task, polling and WebSocket can also be used.

Polling means the application periodically requests the server for updates-such as checking for new messages every ten seconds. This is easy to implement, but frequent requests consume resources even when nothing changes.

Webhooks don't create a permanent connection. The service sends an HTTP request only after a predefined event. This is ideal for server-side integrations, notifications, and automation.

WebSocket establishes a long-lived two-way connection between client and server. Both sides can send data at any time. This suits chats, online games, trading terminals, and other applications requiring real-time data exchange.

For a deeper look at persistent connections, see WebSocket explained: how real-time data exchange works.

The choice depends on your data needs. Use an API if the application decides when to fetch data; use a webhook for automatic event-driven responses; use WebSocket for continuous, real-time, two-way data streams.

How to Set Up a Webhook and Key Considerations

Creating a Webhook Endpoint

To use webhooks, the receiving system needs a publicly accessible URL that external services can send HTTP requests to-known as a webhook endpoint.

The developer creates a handler to process incoming data, verify it, and perform the necessary action. This URL is then entered into the source service's settings.

For example, an endpoint might look like:

https://example.com/webhooks/payment

When the relevant event occurs, the service sends the request to this address.

It's important that the endpoint is accessible from the internet and supports HTTPS. For local development, you can use tunneling tools or test services that temporarily provide a public address for your machine.

Webhook Authentication

A webhook endpoint is open to incoming requests, so you shouldn't trust every request blindly.

If an attacker learns the webhook address, they could try sending fake events. That's why many services sign webhook requests with a secret key.

The receiving system calculates the signature and compares it with the one provided by the service. If they match, you can be sure the data is from the expected source and hasn't been tampered with.

Additional security measures can include secret tokens, HTTPS verification, and IP restrictions if the service supports them.

Retries and Duplicate Events

Webhooks can't guarantee that every request will be processed successfully the first time. The server may be temporarily unavailable, the connection might drop, or processing could take too long.

Many platforms implement retry mechanisms: if the endpoint returns an error or fails to respond, the service tries again later.

Because of this, the same event may arrive more than once. Your application should be able to recognize duplicates and avoid performing the same action multiple times.

This is especially crucial for payments. If a payment success webhook arrives twice, your system shouldn't credit the balance, create two orders, or ship the product twice.

To prevent this, use an event identifier. Before taking action, the application checks whether it has already processed that ID-a practice known as idempotent processing.

Logging and Response Codes

After receiving a webhook, the server should return an HTTP status code-usually 200 for successful processing.

If the server returns an error, the external service may treat delivery as failed and retry.

It's not always best to perform heavy processing directly in the webhook endpoint. If an operation takes a long time, quickly validate and queue the event, return a success response, and process the event further in the background.

Logging is important as well. Record the time, event type, ID, and processing result. This helps diagnose why a notification wasn't handled or why a service tried to resend it.

A properly configured webhook is more than just a URL for POST requests. Reliable integration means considering source verification, retries, duplicates, errors, and possible downtime.

Conclusion

A webhook lets one system automatically notify another about an event without constant API polling. This is especially useful for payments, notifications, service integrations, automation, and other processes that require a quick reaction to changes.

The main difference between webhooks and a regular API lies in the direction of interaction: with an API, the client requests data; with a webhook, the source service sends a notification after an event. Webhooks don't replace APIs-more often, both work together.

If your system needs to fetch data on demand, perform searches, or modify objects, use an API. If you need to automatically react to specific events, use a webhook. For ongoing, real-time, two-way data exchange, WebSocket is typically used.

When implementing webhooks, consider not just sending HTTP requests, but also security, signature verification, retries, duplicate protection, and robust error handling. These details turn a simple webhook endpoint into a reliable integration between services.