Webhooks : Understand in 3 Minutes

Problem Statement

Webhooks are automated messages sent from apps when something happens. They're the solution to the frustrating and inefficient "Are we there yet?" problem in software integrations. Instead of your application constantly asking (polling) another service for updates—like checking every 10 minutes for a new payment or a completed form submission—webhooks make the other service call you the instant the event occurs. Think of the last time you built a feature that needed real-time data from another platform; webhooks are how you get that data without wasting resources and introducing delay.

Core Explanation

At its core, a webhook is a simple callback over HTTP. It’s a way for App A (the provider) to notify your App B (the receiver) about an event by making an HTTP POST request to a URL you provide.

Here’s how it works:

1. You Give a URL: You register a public endpoint (e.g., https://yourapp.com/webhooks/payment-processed) with a service that supports webhooks (like Stripe or GitHub).
2. They Call It: When a specified event happens in their system (e.g., invoice.paid or push), their server creates a payload of data about that event and sends it as an HTTP POST request to your endpoint.
3. You Act on It: Your server receives the request, verifies it’s legitimate, parses the data, and triggers the corresponding business logic in your app.

A simple analogy is "reverse API." With a normal API, you call them. With a webhook, they call you. It's like asking a restaurant to text you when your table is ready (webhook) versus walking back to the host stand every two minutes to ask (polling).

Practical Context

Use webhooks when you need near real-time, event-driven updates from an external service. They are ideal for automating workflows, syncing data between systems, and triggering immediate actions. Common use cases include processing payments (Stripe sends you a webhook on success), updating a database when a user signs up in another app, or triggering a CI/CD build when code is pushed to a repository (like GitHub Actions).

Avoid webhooks for low-volume events where a simple scheduled job is sufficient, or when the client application (like a mobile app) needs the update, as you can't reliably send a webhook to a device that might be offline. In those cases, polling or a persistent connection (like WebSockets) might be a better fit.

You should care because webhooks are the backbone of modern, decoupled, and efficient third-party integrations. They save server resources, reduce latency, and enable event-driven architectures.

Quick Example

Imagine you need to know when a customer's subscription renews via Stripe. Instead of polling their API, you'd set up a webhook endpoint:

// A simple Express.js endpoint for a Stripe 'customer.subscription.updated' webhook
app.post('/webhooks/stripe', express.raw({type: 'application/json'}), (request, response) => {
  const event = request.body; // Contains the subscription data
  if (event.type === 'customer.subscription.updated') {
    const subscription = event.data.object;
    // Update YOUR database with the new subscription status
    updateUserSubscription(subscription.customer, subscription.status);
  }
  response.json({received: true});
});

This example demonstrates the passive nature of webhooks. Your code sits idle, waiting for Stripe to deliver the event. When they do, you immediately update your system's state, keeping it perfectly in sync.

Key Takeaway

Think of webhooks as a subscription service for events: you give a service your number (URL), and they call you only when there's news, eliminating wasteful polling and enabling real-time automation. For an excellent deep dive on implementation patterns, check out Webhooks.fyi.