An order lands on the marketplace, but the warehouse screen has not shown it for half an hour. A payment came through, yet the accounting system knows nothing about it. More often than not the data is fine; the problem is how the news reaches the system. That is where the answer to what is a webhook begins: when something happens, the source system sends a message by itself to an address you have chosen.
In this guide we explain what a webhook is, how it differs from polling and from an ordinary API request, what a webhook is made of, where it is used in business systems, how to design the receiving side, how to secure it, how to handle failures and retries, which metrics to watch and how to implement it in six steps. All example figures are illustrative; they are not measurements of any specific system or industry.
What Is a Webhook?
A webhook is an HTTP request that a system sends to a pre-registered web address when an event occurs in it, such as an order being paid, stock changing or a parcel being delivered. The receiver does not ask; the news arrives. That is why it is sometimes called a "reverse API" or an event notification.
The analogy is simple. Polling is checking your mailbox every five minutes, and most checks come back empty. A webhook is a phone call: it rings when there is news. But if nobody picks up, the caller tries again after a while, and that detail makes up much of this article.
We recommend reading: What is API integration? A guide to connecting your systems
What Is the Difference Between a Webhook, Polling and a Normal API Request?
All three move data between systems; the difference is who starts the exchange and when the news arrives. A normal API request pulls data at the moment you need it, polling repeats that automatically at fixed intervals, and a webhook is the source pushing the data the instant the event happens.
| Topic | Normal API request | Polling | Webhook |
|---|---|---|---|
| Who starts it? | You, when you need data | You, on a timer | The source system, at event time |
| Delay before you know | Depends on when you ask | Half the interval on average | Usually seconds |
| Empty requests | None | Many; it asks even when nothing happened | None; only when there is an event |
| Load on the source | Low | Constant and disproportionate | As many as there are events |
| What the receiver needs | To be a client | To be a client | A publicly reachable endpoint and signature checks |
| Risk of missed news | Low | Low; caught on the next poll | Depends on retries if the receiver is down |
| Best for | Fetching details, reports | Systems that offer no webhooks | Status changes, near-real-time flows |
In practice all three are combined: the event arrives by webhook, the details are fetched with an API request, and a daily reconciliation query catches anything that slipped through.
How Much Does Polling Waste?
A system that polls every five minutes makes 288 requests a day (24 hours × 12). If only 10 real orders arrive per day, 278 polls come back empty: 278 ÷ 288 ≈ 96.5%. And because an order can land at any moment between two polls, the average wait is half the interval: 5 ÷ 2 = 2.5 minutes. With a webhook the same news arrives in about 1 second.
Shortening the interval does not fix this. Polling once a minute means 1,440 requests a day; the delay shrinks (30 seconds on average) but the empty share grows (1,430 ÷ 1,440 ≈ 99.3%). Source systems also tend to enforce rate limits, so aggressive polling can get you throttled for no good reason.
What Is a Webhook Made Of?
A webhook has five parts. Knowing them helps both when you build one and when you hunt for a fault.
- Event: a name that says what happened, for example
order.paid. - Payload: the event data, usually JSON with fields such as event ID, time, order number and amount.
- Receiver URL: the address in your system where the message is sent; it is registered in the source system.
- Signature header: a value showing that the message really came from the source and was not altered on the way; it is produced with a shared secret.
- Response code: the receiver's answer. A 2xx means "received"; any other code, or no answer at all, counts as "not delivered" and starts the retries.
Picture a typical message: event name order.paid, event ID evt_8f21, creation time, order number 1042 and amount ₺2,450. The headers carry the send time and the signature. The receiver takes it, verifies it and answers 200.
Where Are Webhooks Used in Business Systems?
Any time-sensitive flow that changes state is a candidate. The most common uses are these.
- Order status: new order, cancellation and return notices reach order management instantly.
- Payment result: knowing whether a payment succeeded or failed decides whether to confirm or hold the order.
- Stock change: when one channel sells an item, the other channels are updated; delay raises the risk of overselling.
- Shipping update: shipped, out for delivery and delivered notices go to the customer and the marketplace.
- Invoice status: whether an e-invoice (e-Fatura) was sent, delivered or rejected is written back to the order.
We covered how these flows are built, topic by topic, in these guides:
We recommend reading: What is marketplace integration? Order, stock and price flows
We recommend reading: What is shipping integration? Labels, tracking and reconciliation
We recommend reading: What is e-invoice (e-Fatura) integration? Invoice status and error handling
How Should the Receiving Side Be Designed?
The receiver has two rules: answer fast and never process the same event twice. The first matters because most senders use a timeout; if your answer takes more than a few seconds, the sender assumes failure and retries.
Answer fast, do the work later
The receiver accepts the message, verifies the signature, writes it to a queue and immediately returns 2xx. The real work, such as reducing stock or issuing an invoice, is done by a separate worker reading from the queue. A heavy task then cannot delay the answer and trigger needless retries.
Never process the same event twice (idempotency)
If the sender does not get an answer, it sends the event again; on a flaky network the receiver may have done the work and the answer may simply have been lost. The fix is to store each event ID and skip it if it was already processed.
Example: evt_8f21 arrives for order 1042, stock of 50 is reduced by 2 to 48, and the ID is written to a "processed" table. The sender never received the answer and resends the same event. The receiver finds the ID in the table, skips the work and returns 200; stock stays at 48. Without the protection, stock would have dropped to 46 and a second invoice would have been issued.
How Is Webhook Security Handled?
Because the receiver address is open to the internet, anyone can send a request to it, so the origin of every incoming message must be verified. Four measures are the foundation.
| Measure | What it does | Example |
|---|---|---|
| Signature verification | Proves the message came from the source and is unchanged | Compute a signature from the body and the time with the shared secret and compare it with the header in constant time |
| Timestamp tolerance | Blocks replay of an old message | Reject the message if the send time is more than 5 minutes old |
| HTTPS | Protects the message from being read in transit | Accept only encrypted connections |
| Limiting exposure | Avoids leaving the endpoint needlessly open | An unguessable path, rate limits and, where possible, a list of allowed source addresses |
When verifying the signature, use the raw body exactly as received; if you reformat the JSON first, the signature will not match. The shared secret belongs in a secure settings store, not in the code. For layered protection and secret storage in full, see the guide below.
We recommend reading: How to secure an API: authorization, rate limits and webhook signatures
How Are Failures and Retries Handled?
If the receiver is down or returns an error, the sender retries at growing intervals. In our example the gaps are 1, 2, 4 and 8 minutes, so attempts happen at minutes 0, 1, 3, 7 and 15: five attempts over 15 minutes. If all fail, the event lands in a dead-letter queue or a manual review list and raises an alert.
| Situation | What happens | What the receiver should do |
|---|---|---|
| Receiver is down | The sender retries at intervals | Process the backlog when back up; watch queue depth |
| Response was slow | The sender retries after a timeout | Return 2xx at once and do the work in the background |
| Same event arrived twice | Risk of double processing | Protect with the event ID |
| Order was scrambled | "Paid" may arrive before "created" | Check the event time or fetch the current state from the API |
| All attempts exhausted | Risk of losing the event | Dead-letter queue, an alert and a daily reconciliation query |
Do not assume order is preserved. Two events can arrive within the same second over different paths; every event should carry a time or version field, and the receiver must not let an older message overwrite a newer state. For events that still never arrive after all retries, a daily reconciliation (asking the source "what happened since yesterday?") is the safety net.
Which Metrics Show the Health of a Webhook?
Three metrics are enough: delivery success rate, average delay and duplicate rate. Take an illustrative day: the source sent 1,000 events; 985 arrived on the first attempt, 11 after retries and 4 ended up in the dead-letter queue.
- Delivery success rate: delivered ÷ sent. Including those delivered after retries: (985 + 11) ÷ 1,000 = 99.6%; on the first attempt alone, 985 ÷ 1,000 = 98.5%. The 4 events in the dead-letter queue are 0.4%.
- Average delay: first-attempt events took 1 second, and the 11 retried events were late by 3 minutes (180 s) on average: (985 × 1 + 11 × 180) ÷ 996 = 2,965 ÷ 996 ≈ 3.0 seconds. The average looks small, so also watch the maximum for the outliers.
- Duplicate rate: the receiver got 1,026 requests carrying 996 distinct event IDs; 30 duplicates ÷ 1,026 ≈ 2.9%. If the rate suddenly climbs, there is a problem at the sender or in the receiver's response time.
Set thresholds for these three and alert when they are crossed, for example when the success rate falls below 99%. Thresholds depend on your business.
What Is the Cost and Benefit of Building Webhooks?
Let us run the numbers with the scene figures. Polling produces 288 × 30 = 8,640 requests a month, while a webhook produces 10 × 30 = 300 (before the retry allowance); request volume falls by about 96.5%. The real gain is speed: the average delay of 2.5 minutes drops to about 1 second.
A monetary example (illustrative): building the receiver endpoint, signature check, queue and monitoring takes 6 person-days × ₺9,000 = ₺54,000. Monthly benefit: preventing 2 oversold orders a month caused by delayed stock (2 × ₺600 = ₺1,200) and saving 3 hours of manual reconciliation (3 × ₺300 = ₺900), for ₺2,100 in total. Payback: 54,000 ÷ 2,100 ≈ 25.7 months. For a single flow that looks long.
Once the receiving infrastructure exists, extra flows are cheap. If you build five flows for orders, payments, stock, shipping and invoices: the first costs ₺54,000, and each of the other four takes 2 person-days × ₺9,000 = ₺18,000, so ₺72,000 more, ₺126,000 in total. Monthly benefit is 5 × ₺2,100 = ₺10,500. Payback: 126,000 ÷ 10,500 = 12 months. In other words, the value of webhooks comes not from one flow but from reusing the shared infrastructure. These figures are examples; recalculate with your own volumes.
What Steps Does a Webhook Integration Follow?
Six steps keep the risk low.
- List the events: Which events matter to the business (payment, stock, shipping...)? Subscribing to unneeded events only adds load.
- Write the receiver endpoint: Accept the raw body, write it to a queue and return 2xx quickly.
- Verify the signature: Shared secret, timestamp tolerance and HTTPS.
- Add duplicate protection: An event ID table, plus a time or version check against out-of-order delivery.
- Test failure and retry scenarios: Switch the receiver off on purpose, send the same event twice, answer slowly.
- Monitor and reconcile: The three metrics, alert thresholds and a daily reconciliation query.
What Are the Most Common Webhook Mistakes?
- Doing the work before responding: Heavy work delays the answer, the sender retries and the duplicate problem appears.
- Skipping duplicate protection: Double stock deduction, double invoices and double emails are the usual results.
- Not verifying the signature: Anyone who knows the address can send a fake order or payment notice.
- Assuming order is preserved: An old message overwrites the new state.
- Forgetting reconciliation: Relying on the webhook alone makes lost events invisible.
- Not monitoring: When the receiver goes quiet, the missing news can go unnoticed for days.
We recommend reading: What is an order management system? Order flow across channels
Integration and Event-Driven Flows with İnovabil
At İnovabil our focus is building software from scratch, tailored to each company, and integration is an important part of it. If you need event-driven flows between your systems, we suggest settling in the requirements analysis, in writing, which event is handled by a webhook, which by an API query and which by a daily reconciliation.
We built logistics and shipment planning with wholesale order management for Karyak; warehouse management and a complaint and support management system for Sleepy; a prepaid shipping system for Kredili Kargo; and a purchasing system for İZBAN. Send us a short note on your systems and on which delayed news costs you the most, and we will put together an assessment together.
We recommend reading: Our integration service
Frequently Asked Questions
What is a webhook and how does it work in short?
It is an HTTP request a system sends to a web address you registered when an event happens in it. The receiver does not ask; the message arrives, the receiver verifies it and answers with a 2xx code.
What is the difference between a webhook and an API?
With an API you ask for the data; with a webhook the source sends it to you at event time. They are used together: the event arrives by webhook and the details are fetched through the API.
What happens if a webhook message is lost?
The sender usually retries at intervals, and if every attempt fails the event lands in a dead-letter queue. A daily reconciliation query is still the safe way to catch anything missed.
If the same webhook arrives twice, is it processed twice?
It is if there is no protection. Storing each event ID and skipping those already processed (idempotency) prevents double stock deduction and double invoices.
Is a webhook address secure?
Not on its own; because the address is publicly reachable, you need signature verification, timestamp tolerance and HTTPS. Without them anyone can send a fake notification.