What Is a Webhook? How It Differs from an API

01What Is a Webhook and How Does It Work?

A webhook is a simple mechanism that lets two pieces of software notify each other about events. When something happens inside a system (for example, when a payment is confirmed), it sends an HTTP request, usually a POST request, to a URL you specify. The details of the event are generally in the request body, in JSON format.

This structure is sometimes also called a reverse API or an event trigger, because the party that starts the communication is not the one requesting the data but the system producing it. You say once, "when this event happens, notify me at this address," and the rest happens automatically.

To understand how a webhook works, it helps to first know the answer to what an API is. A webhook is part of the API world, but the direction is reversed.

1. The event happens: a new order, a return request, an out-of-stock item, a payment confirmation.
2. The source system sends a POST request to the registered webhook address.
3. The receiving system validates the request, processes the data and returns a response such as 200.
4. If no response arrives, the source system usually retries the request at set intervals.

02The Difference Between a Webhook and an API

In classic API use, the client asks the server at regular intervals, "is there anything new?" This method is called polling. If there's no new data, every request is wasted; if there is, you have to wait until the next query.

This is exactly where the difference between a webhook and an API shows: with a webhook there is no asker, only a notifier. The notification arrives the moment the event happens, and no unnecessary traffic is created. However, a webhook doesn't replace everything; you still need an API to list, filter or update historical records.

03Webhook Use Cases

Webhook usage turns up in almost every digital job. Payment providers, shipping companies, marketplaces, email services, code repositories and communication tools mostly deliver event notifications through webhooks.

E-commerce and payments

When a customer completes a payment, the payment infrastructure sends a "payment successful" notification to your store and the order is confirmed automatically. In redirect-based payments such as 3D Secure, this is what keeps the order from being lost even if the browser closes. The order flow is at the heart of any e-commerce integration.

Shipping and marketplaces

When a shipment departs or is delivered, the shipping system can report the status, and an automatic SMS or email goes to the customer. Likewise, in shipping integration and marketplace integration projects, events such as new orders, cancellations and returns are processed instantly.

Software development and team tools

Typical webhook scenarios include starting tests and the release process when a new commit is pushed to a code repository, posting a notification to the team's messaging channel when a form is filled in, or updating the calendar when a reservation comes in.

04An Example Webhook Request

A webhook request usually carries the type of the event, its time and the data of the record concerned. The example below is a typical body that might be sent when an order is created. Field names differ for every service; rely on the service's own documentation.

On the receiving side, a small endpoint that handles this request is enough. Below you see a simple example written with Node.js and Express. In a real project, signature verification and a queue structure must be added.

{
  "event": "order.created",
  "created_at": "2026-01-15T10:24:00Z",
  "data": {
    "order_id": "10458",
    "total": 1249.90,
    "currency": "TRY",
    "status": "paid"
  }
}

const express = require('express');
const app = express();

app.post('/webhooks/siparis', express.json(), (req, res) => {
  const olay = req.body;
  // 1) Verify the signature  2) Add to the queue  3) Return a response immediately
  console.log('Gelen olay:', olay.event);
  res.sendStatus(200);
});

app.listen(3000);

05How to Secure a Webhook

A webhook address is an endpoint open to the internet. Anyone who knows the address can send a fake request to it. That is why you should trust no incoming request without signature verification.

Most serious services sign the request with a shared secret key and send the signature in an HTTP header. The receiving system performs the same calculation and compares the signatures; a request that doesn't match is rejected.

• Use HTTPS addresses only; don't send data over plain HTTP.
• Always apply verification methods such as an HMAC signature.
• Check the timestamp in the request to prevent old requests from being replayed.
• Don't write the secret key into the code repository; store it in an environment variable.
• Check the schema of incoming data before writing it directly to the database.

06Common Mistakes and Fixes

Setting up a webhook is easy, but running it reliably takes care. The most common problems in projects are repeated requests and slow responses.

The same event processed twice

When the source system gets no response, it sends the request again, so the same order can arrive twice. The solution is an idempotent operation design: record each event's unique ID, and if an already processed ID arrives, just return a success response and move on.

Timeouts

If the endpoint tries to do long jobs such as issuing an invoice or sending an email while handling the request, the response is delayed and the source system counts an error. The right method is to take the request, add it to a job queue and respond immediately; the heavy work runs in the background.

Out-of-order events

Events may not always arrive in the order they occurred; a "shipped" notification can arrive before a "paid" notification. Store the event time in your records and evaluate status transitions according to that time.

07Webhook or Ready-Made Automation Tool?

In simple scenarios, automation tools that listen for webhooks without code can do the job. We covered the strengths and weaknesses of these tools in detail in our article on what low-code is. But for the flows at the heart of the business, such as orders, payments and stock, it is important that you stay in control.

If your business rules are specific, several systems are connected to each other or data volume is growing, it is more reliable to build the webhook architecture inside your own software. In this respect, a custom software development approach reduces dependence on intermediate layers.

Our software solutions and integrated solutions approach is also based on this principle: systems talk to each other directly, and unnecessary layers in between are removed.

08Checklist Before Setting Up a Webhook

Answering the questions below before setting up an automatic notification infrastructure prevents most later problems from the start.

1. Which events are really needed? Subscribing to every event creates unnecessary load.
2. Is the endpoint reachable over HTTPS, and does it verify signatures?
3. Is a unique ID record kept for repeated events?
4. Are failed requests logged and traceable?
5. Is there a backup check that recovers the data through the API if a webhook doesn't arrive?
6. In critical steps such as accounting and invoicing, is the risk of double entry checked through accounting integration?