What Are Webhooks?

The problem with polling

Imagine you have ordered a package and want to know when it arrives. One option: walk to your front door every five minutes and check. That is polling — your application repeatedly asking an API "did anything change?" Most of the time the answer is no, so you are wasting requests, burning rate limits, and adding latency. The package could arrive one second after you walked away from the door.

Webhooks flip the model

A webhook is a URL on your server that the external service calls when something happens. Instead of you asking Stripe "did the payment go through?", Stripe calls your endpoint and tells you. You register a callback URL with the provider, and from that point on you receive real-time HTTP POST requests every time an event occurs — payment succeeded, subscription cancelled, new user signed up.

The anatomy of a webhook payload

Every webhook delivery is an HTTP POST request with a JSON body. The shape varies by provider but they all include an event type and the relevant data. Here is a simplified Stripe payment event:

{
  "id": "evt_1Ng3kJ2eZvKYlo2CvCcmvjaD",
  "type": "payment_intent.succeeded",
  "created": 1735689600,
  "data": {
    "object": {
      "id": "pi_3Ng3kJ2eZvKYlo2C1K9RMWMW",
      "amount": 4900,
      "currency": "usd",
      "status": "succeeded",
      "metadata": {
        "userId": "user_abc123",
        "orderId": "order_xyz789"
      }
    }
  }
}

Event types and filtering

Providers send dozens of event types. Stripe alone has over 200. When you register your webhook endpoint with a provider, you typically choose which event types you care about — otherwise every event floods your endpoint. Common events you will handle: payment_intent.succeeded, invoice.payment_failed, customer.subscription.deleted, user.created.

• payment_intent.succeeded — a one-time payment completed — fulfil the order
• invoice.payment_failed — a subscription renewal failed — notify the customer
• customer.subscription.deleted — subscription cancelled — downgrade access
• checkout.session.completed — Stripe Checkout finished — provision the product

Why webhooks are the default in production

Polling introduces latency proportional to your polling interval. With webhooks, the event triggers your code within seconds of it happening. There is no wasted network overhead. For time-sensitive flows — like provisioning access after a payment — polling is simply too slow. Every payment processor, auth provider, communication platform, and CI/CD tool that matters uses webhooks as the primary event delivery mechanism.