webhooks

Webhooks

Webhooks are "user-defined HTTP callbacks". They are triggered by some event in a source system (e.g., Stripe, GitHub) and sent to a destination system (Your API) to notify it.

When to Use

• Payment Confirmations: Stripe notifying you a payment Succeeded.
• CI/CD: GitHub notifying Jenkins that code was pushed.
• Async Processing: A 3rd party AI service notifying you that generation is complete.

Quick Start

// Your Webhook Handler (Receiver)
app.post(
  "/webhooks/stripe",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["stripe-signature"];

    try {
      // Verify the event came from Stripe and hasn't been tampered
      const event = stripe.webhooks.constructEvent(
        req.body,
        signature,
        START_SECRET,
      );

      if (event.type === "payment_intent.succeeded") {
        fulfillOrder(event.data.object);
      }

      res.json({ received: true });
    } catch (err) {
      res.status(400).send(`Webhook Error: ${err.message}`);
    }
  },
);

Core Concepts

Verification (Security)

Since Webhook endpoints are public, anyone can POST to them. You must verify the Signature (HMAC) usually sent in a header to prove the sender's identity.

Retries

If your server returns an error (500) or times out, the sender usually retries with exponential backoff. Your endpoint must be Idempotent.

Best Practices

Do:

• Respond Immediately (200 OK). Don't process the business logic in the request. Queue it (SQS/Redis) and process async. If you timeout, the sender will retry.
• Verify Signatures rigorously.
• Support Payload Versioning.

Don't:

• Don't rely on the order of delivery.
• Don't assume you will receive the event only once (Idempotency is key).

Troubleshooting

Error	Cause	Solution
Signature Verification Failed	Body parsing issue.	Ensure you verify the Raw Body, not the parsed JSON object.
Timeout	Processing taking too long.	Move logic to a background job; return 200 immediately.