Webhook: when the API calls you, instead of you calling it

I'm Yuliia Asliaieva, a Business Analyst. Over the years of working with integration solutions in fintech, banking, and the insurance domains, I've learned one important rule: even the most complex technical concepts can and should be explained simply.  When working with integrations, frequently encounter two approaches to data exchange. The first one is to constantly poll for status updates, which overloads the system. The second one is to use a Webhook. What does this mean in simple terms, and why is it like a "we'll call you back" feature rather than hanging on the line? Let's figure it out.

What is a Webhook in simple terms?

Imagine you ordered a pizza and you call the restaurant every 5 minutes: - Is the pizza ready? - No.

(5 minutes later) - Is it ready now? - No.

(Another 5 minutes later)

- How about now?

- No, 10 more minutes!

This process is known as Polling, when your application repeatedly sends requests to the API asking, "Is there new data yet?" This approach overwhelms the server and unnecessarily consumes resources.

Now, consider an alternative: You place your order, and the restaurant tells you: "We will notify you once the pizza is ready." You can focus on other tasks until -ring ring! - you get the call: "Your order is ready and out for delivery."

This is a Webhook—a mechanism where the service proactively alerts you when an event occurs. You don't have to pull for updates; the data is pushed to you. A Webhook acts as a "callback." You provide your "phone number" (a destination URL), and whenever the event triggers, the service automatically sends a notification containing the relevant data.

Key Differences:

🟤 Standard API (Request-Response):YOU ask → THE SERVICE responds.Initiator: you. You control when to make a request to get data right now.

🟢 Webhook (Event-Driven):SERVICE → something happens → automatically sends data → YOUR SERVER.Initiator: the service. It decides when to send you data (triggered by an event).

🔵 Polling:

YOU ask: "Anything new?" → SERVICE: "No" → YOU again: "How about now?" → SERVICE: "Yes."

Initiator: You. You regularly check the service at specific intervals to see if new data has appeared. This is used when a service doesn't support Webhooks, but you still need to track changes. It is the most "resource-heavy" method for the server because many requests go to waste.

Let’s look at some real-life examples of Webhooks (you definitely use them every day)

📱 Package Tracking

Without Webhooks (Polling): Every 10 minutes, you open the delivery service's website and enter your tracking number: "Where is my package? How about now? And now?"

With Webhooks: The service sends you an SMS or a push notification: "Your package has arrived at the pickup point." THEY call you; you don’t have to call them.

💳 Payments (Stripe, PayPal, LiqPay)

A user pays for an order on a website. The payment gateway processes the transaction (which can take 5–30 seconds). Instead of your server asking every second, "Did they pay? How about now?", the payment system sends a webhook itself: "Payment successful! Here are the transaction details."

🎬 YouTube / Twitch

You subscribe to a channel → a YouTuber uploads a new video → you get a notification. That is a webhook in action.

💬 Chatbots (Telegram, Slack)

A user sends a message to a Telegram bot → Telegram doesn't wait for your server to ask, "Are there any new messages?" → Telegram immediately sends a webhook to your server with the text of the message.

The Anatomy of a Webhook: How It Works Under the Hood

Step 1: Webhook Registration (Subscription)

You tell the external service:

"Hey, whenever event X happens on your end, send the data here:"

POST https://api.service.com/webhooks{  "url": "https://myapp.com/webhooks/payment-received",  "events": ["payment.success", "payment.failed"]}

What you’ve provided:

• url: Your endpoint where the service should send the data.

• events: The specific events you are interested in.

The service responds: "Got it! Recorded. As soon as a payment.success occurs, I’ll send the data to you."

Step 2: An Event Occurs

A user pays for an order → the payment system logs this as a payment.success event.

Step 3: The Webhook is Triggered (Callback)

The payment system automatically makes an HTTP POST request to your registered URL.

Step 4: Your Server Processes the Webhook

Your backend receives the data and performs the following:

1. It verifies the signature (X-Webhook-Signature) to ensure the request actually came from the payment system and not a hacker.

2. It updates the order status in the database: "ORDER-789 → PAID".

3. It sends an email to the customer: "Thank you for your purchase!"

4. t responds to the service with a 200 OK status (so the service knows you successfully received the data).

What if your server doesn't respond with 200 OK?The payment system will think, "Hmm, they didn't get the data," and will attempt to resend the webhook after 5 minutes, then 15 minutes, then an hour... This is known as a Retry Mechanism.

Webhook vs API: Which One to Use?

Criterion	API (Request-Response)	Webhook (Event-Driven)
Initiator	You request the data	The service sends the data
When to Use	When you control when the data is needed	When events occur unpredictably
Load (Overhead)	Polling = high volume of requests	Only when an event occurs
Real-time	Latency (depends on polling frequency)	Near-instant
Examples	"Show product list", "Get user info"	"New payment", "Email opened", "File uploaded"
Dependency	Your server makes requests	Your server receives requests

The best approach is a hybrid model:

• Leverage Webhooks for real-time event handling.

• Use APIs (Request-Response) to retrieve detailed information, history, or to validate data on-demand.

  
  

This synergy keeps your data synchronized while minimizing system overhead.

Example for Analysts: CRM Integration

Imagine you are a Business Analyst on an e-commerce project. You need to integrate the system with a payment gateway (e.g., LiqPay).

Scenario 1: User pays for an order

Without Webhooks (Bad Practice ):

1. The user clicks "Pay".

2. Your system redirects them to the LiqPay payment page.

3. The user completes the payment.

4. LiqPay redirects the user back to your website.

5. Your backend polls the LiqPay API every 5 seconds: "Has USER123 paid yet?"

6. LiqPay responds: "No", "No", "No"... "Yes!"

7. Your system finally updates the order status.

Issues:

🔴 Data Loss Risk: If the user closes the tab immediately after paying but before the redirect happens, your site might never "learn" about the successful transaction.

🔴 Resource Waste: You are making dozens of redundant API requests, which could exhaust your API rate limits.

🔴 Latency: There is a noticeable delay between the actual payment and the status update in your database.

With Webhooks:

1. The user clicks "Pay".

2. Your system redirects them to the LiqPay page.

3. The user completes the payment.

4. LiqPay immediately sends a webhook to your designated URL:POST https://yourdomain.com/api/webhooks/liqpay   { "status": "success", "order_id": "123", "amount": 1500 };

5. Your backend instantly updates the order status upon receiving the data.

6. When the user returns to the site, they immediately see: "Payment Successful!"

   
   

Advantages:

✅ Near-Instant: Minimal latency (0–2 seconds).

✅ Reliability: Your server receives the data even if the user closes their browser or loses their internet connection right after the payment.

✅ Efficiency: Saves API resources by eliminating unnecessary polling.

✅ Rich Data: Your system automatically receives comprehensive transaction details in the payload.

When are Webhooks a Bad Idea?

A Senior BA must know when to say "No." Webhooks are not a "silver bullet." Sometimes, a good old REST API is the better choice.

❌ 1. When data is needed "here and now" (On-demand)If a user clicks a "Show user list" button, they don't want to wait for the server to "call back." They need an immediate response. If an action is initiated by a user who is waiting for a screen to update, use a standard GET API request.

❌ 2. When your server is "hidden" from the worldA Webhook is like an incoming call. To receive one, your server must have a Public IP address that is visible to the internet.If your system operates within a closed security loop (e.g., an internal banking network, a local environment, or a test server behind a VPN), an external service technically cannot send data there.Solution: In such cases, use Polling (periodically asking: "Is there anything new?").

❌ 3. When an immediate two-way response is requiredWebhooks work on a "fire-and-forget" basis. The service does not expect you to return complex calculations or logic in your response to the webhook.If an external service needs data from you to continue its own process, that should be an API call, not a webhook.

Integration Readiness Checklist for Business/System Analysts

When writing requirements for webhooks, use this list to ensure everything is covered with the development team:

1. Basic Configuration

• Endpoint URL: What address are we providing to the partner?

• Events List: Which specific events are we subscribing to?

• Payload Structure: Do we have a sample JSON of the incoming data?

2. Security

• Verification: How do we verify the callback (Signature verification, secret tokens)?

• Secret Management: Where will we store the security keys?

• Failure Policy: What happens if the signature is invalid? (e.g., Reject with 400/401 + log the event).

3. Processing & Logic

• Idempotency: How do we protect against duplicate notifications (e.g., if the same webhook is sent twice)?

• Performance: Can we process the request within the timeout limit (usually 3–5 seconds)?

• Mapping: How do the fields from the webhook map to our database?

4. Error Handling & Recovery

• Retry Policy: If our server is down, how many times (and how often) will the service attempt to resend the data?

• "Not Found" Scenarios: For example, what should we do if we receive a payment confirmation for an order that doesn't exist in our database?

To sum up:

A Webhook is the "Don't call us, we'll call you" principle in action.

To help you remember the difference, let’s use a restaurant analogy:

📞 Classic API:This is when you call the restaurant and ask, "Is my table ready yet?" You stay on the line while the host checks. You are the one initiating the contact.

🔔 Webhook: This is when you leave your phone number and say, "Give me a call once a table opens up." You go for a walk in the park, and the restaurant "pings" you as soon as the event occurs.

Art of Business Analysis training schedule 

News and articles on business analysis: 

• Telegram 

• Linkedin