What is webhook in simple words and how not to lose events

When a developer first encounters integrations, the word webhook almost always appears.

At first glance, everything looks simple: the service sends an HTTP request when an event occurs. But in practice, it is with webhooks that most often problems arise:

• events come twice
• events ** get lost **
• integration is broken without errors

To avoid this, it is important to understand not only the definition of webhook, but also how it works at the architectural level.

## What is webhook

**Webhook is an HTTP request that the service automatically sends to your application when an event occurs. **

Put simply:

webhook is a notification from a service that comes immediately after an event.

Examples of events:

Instead of constantly asking the API for new data, the service reports events.

## How Webhook differs from a regular API

There are two main ways to get data from another service.

### Polling (ordinary API)

The app regularly asks the server:

GET /orders
GET /orders
GET /orders

It creates:

• overloading the server
• delays in obtaining data
• inefficient use of the API.

### Webhook

The service itself sends a request when an event occurs:

POST https://your-app.com/webhook

Once an event occurs, the server sends an HTTP request with data.

This is called the event-driven model – the system responds to events.

## How Webhook Works

Webhook mechanics consists of three steps.

### 1. Endpoint is created

This is a regular HTTP address that accepts requests.

Example:

https://example.com/webhooks/orders

### 2. The service is configured webhook

For example:

event: order_created
url: https://example.com/webhooks/orders

The service remembers where to send data.

### 3. At the event, an HTTP request is sent

When an event occurs, the service sends a POST request:

POST /webhooks/orders
Content-Type: application/json

{
  "event": "order_created",
  "order_id": 12345,
  "amount": 49.99
}

Your server accepts the request and processes the data.

## A simple example of webhook on Node.js

The minimum endpoint for processing webhook can look like this:

import express from "express"

const app = express()
app.use(express.json())

app.post("/webhook", (req, res) => {
  console.log("Webhook received:", req.body)

  res.status(200).send("ok")
})

app.listen(3000)

When the service sends webhook, the data will appear in req.body.

## Where webhooks are used

Webhook is used in almost all modern integrations.

Typical examples:

• ** payment systems** - notice of payment
• Git Repositories - Launching CI/CD
• Telegram bots - receiving new messages
• CRM Systems* – Create and Update Transactions
• ** marketing services** - user events

Any system that requires a real-time response to an event usually uses webhook.

## Why Webhooks Can Come Several Times

Many developers assume that webhook comes ** once **.

That's a wrong assumption.

In practice, webhook can:

• come in a few times
• come in with a delay
• not coming because of a network error.

Most services use the *retry mechanism. If the server does not respond with the 200 code, the webhook will be sent again.

Therefore, the system must be ready for duplicate events.

## How to properly handle webhook

Reliable webhook processing usually includes several components.

Typical architecture:

Webhook request
↓
HTTP endpoint
↓
message
↓
worker
↓
logic

This approach solves several problems:

• prevent loss of events
• protects the server from overload
• it allows you to process events asynchronously.

## Common mistakes when working with webhook

### 1. Long processing of the request

Webhook endpoint should respond quickly.

If the processing takes a long time, the service can decide that the request failed and send the webhook again.

### 2. Absence of idempotence

If webhook comes twice, the system should not create two records.

Often used:

• event_idXX
• request_idXX
• unique keys in the database.

### 3. Lack of logging

Webhook integrations almost always require logging:

• incidental
• error
• repeated delivery attempts.

Without logs, debugging becomes extremely difficult.

## When webhook is better than API

Webhook is best used when:

• you need to get real-time events**
• number of events *unpredictable *
• polling creates too much pressure.

API polling is suitable when:

• events rarely occur
• webhook cannot be configured.

## Outcome

Webhook is a mechanism where the service automatically sends an HTTP request to your application when an event occurs.

It allows you to build event integrations that are faster and more efficient than persistent API requests.

However, for reliable work, it is important to consider:

• re-delivery of webhook
• network errors
• asynchronous event processing.

With the right architecture, webhook becomes one of the simplest and most powerful tools for service integration.