What Is a Webhook? A Plain-English Explanation for Developers

A webhook is a way for one service to notify another service that something happened — in real time, automatically, without anyone asking.

The most useful analogy: a webhook is like a doorbell. You don't stand at the door watching for visitors. Instead, a visitor arrives and presses a button, and your house notifies you. Webhooks work the same way — instead of your application repeatedly asking "did anything happen yet?", the other service tells you when it does.

The Technical Explanation

A webhook is an HTTP POST request sent from one system to another when an event occurs.

When a specific thing happens in Service A (a payment succeeds, a user signs up, a file is uploaded), Service A sends an HTTP POST to a URL you've registered. Your application receives the request, reads the payload, and acts on it.

The payload is usually JSON:

{
  "event": "payment.succeeded",
  "data": {
    "id": "pay_abc123",
    "amount": 4900,
    "currency": "usd",
    "customer_id": "cus_xyz789"
  },
  "created_at": "2026-03-15T14:32:00Z"
}

Your application reads that payload and does something: activates a subscription, sends a confirmation email, updates a database record.

Webhooks vs Polling

Before webhooks, the alternative was polling: your application periodically called an API to check whether anything had changed.

Your app:  Did anything happen? (every 30 seconds)
API:       No.
Your app:  Did anything happen?
API:       Yes! Here's what changed.

Polling works but it's wasteful (most calls return "nothing happened"), slow (you wait up to your poll interval), and expensive (API rate limits, server costs).

Webhooks invert this:

Payment processor:  Something happened. Here it is. (immediately)
Your app:           Got it. Processing now.

Instant notification, no wasted requests, no waiting.

A Concrete Example: Stripe

Stripe processes a payment. Within seconds:

POST https://yourapp.com/webhooks/stripe
X-Stripe-Signature: t=1234567890,v1=abc...

{ "type": "payment_intent.succeeded", "data": { ... } }

Your application: receives → verifies signature → checks event type → activates subscription → sends confirmation email → returns 200 OK.

Key Terms

Webhook endpoint: The URL in your application that receives webhooks. You register this with the sending service.

Payload: The JSON body containing event data.

Signature: A cryptographic hash proving the request came from the expected source. Always verify this.

Event type: The type of event (e.g., payment_intent.succeeded). Different types trigger different handling.

Delivery: A single attempt to POST the webhook. If failed, the sender may retry.

A Minimal Webhook Handler

// Node.js (Express)
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const event = JSON.parse(req.body);
  if (event.type === 'payment_intent.succeeded') {
    // handle payment
  }
  res.sendStatus(200);
});

# Python (Flask)
@app.route('/webhooks/stripe', methods=['POST'])
def stripe_webhook():
    event = request.get_json()
    if event['type'] == 'payment_intent.succeeded':
        pass  # handle payment
    return '', 200

Security: Always Verify Signatures

Anyone can POST to a public URL. Senders include a signature in request headers — a hash of the body using a shared secret. Verify it matches before processing anything. Never skip this step.

When Do You Need Webhook Infrastructure?

For simple cases — one service, one endpoint — a single handler function is fine. As you scale:

• Multiple destinations receiving the same event
• Retry logic when a destination goes down
• Per-destination payload transformation
• Historical logs and replay capability

This is where webhook infrastructure platforms like Bluejay Relay fit in. Bluejay Relay receives webhooks, logs them, transforms payloads, and delivers to multiple destinations with automatic retry.

---

New to webhooks? Start with Bluejay Relay free — set up your first webhook integration in under five minutes.