Receiving Stripe Webhooks: Endpoint Setup & Signature Verification

Step 1: Build a Webhook Endpoint

# Ruby + Sinatra example
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(JSON.parse(payload, symbolize_names: true))
  rescue JSON::ParserError
    status 400
    return
  end

  # TODO: handle the event by type
  status 200
end

Stripe maintains official server libraries for Ruby, Node.js, Python, Go, Java, and PHP; reuse them to reduce low-level parsing work.

Step 2: Register the Endpoint in Stripe

Add the endpoint via the Stripe Dashboard under Developers → Webhooks or create it programmatically through the API. Stripe requires a publicly accessible HTTPS URL in live mode.

Step 3: Verify Stripe Signatures

Stripe signs each webhook with a shared secret and sends the signature in the Stripe-Signature header. Always validate the signature using the raw request body before trusting the payload, and reject events older than five minutes to prevent replay attacks.

# Ruby signature verification
endpoint_secret = ENV.fetch('STRIPE_WEBHOOK_SECRET')
payload = request.body.read
sig_header = request.env['HTTP_STRIPE_SIGNATURE']

begin
  event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret)
rescue Stripe::SignatureVerificationError => e
  puts "Signature verification failed: #{e.message}"
  halt 400
end

// Node.js + Express example
import express from "express";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_API_KEY!);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET!;

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

    try {
      const event = stripe.webhooks.constructEvent(
        req.body,
        signature as string,
        endpointSecret,
      );

      handleStripeEvent(event);
      res.status(200).send("OK");
    } catch (error) {
      console.error("Invalid Stripe signature", error);
      res.status(400).send("Webhook Error");
    }
  },
);

Step 4: Test with Stripe CLI & Hooklistener

Stripe offers multiple testing tools. Use them alongside Hooklistener to forward events into local environments, inspect payloads, and replay failures safely.

Step 5: Handle Events Idempotently

Stripe delivers events at least once and occasionally out of order. Always gate processing on event.type and record event IDs you already handled so retries do not double-charge customers or create duplicate records.

import type Stripe from "stripe";

function handleStripeEvent(event: Stripe.Event) {
  const alreadyProcessed = hasEventBeenHandled(event.id);
  if (alreadyProcessed) {
    return;
  }

  switch (event.type) {
    case "payment_intent.succeeded":
      fulfillSubscription(event.data.object);
      break;
    case "customer.created":
      syncCustomer(event.data.object);
      break;
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  markEventHandled(event.id);
}

• Persist processed event IDs in a durable data store (database or cache with TTL).
• Fetch canonical objects from Stripe’s API when accuracy matters (for example, re-fetch the payment intent by ID).
• Queue heavy work (email, invoicing, ERP sync) so your webhook response remains fast.

Step 6: Operational Best Practices

Key Steps & Tooling Overview

Build Faster with Hooklistener

Further Reading