Spec the Stripe webhook that fulfills paid orders

Vibe codingMedium16 minStripe style

Your task

Your shop runs on Node and Express, and customers pay through Stripe Checkout. When Stripe sends a checkout.session.completed event, your server has to mark the order paid and start fulfillment. A coding agent will build that webhook handler.

Write the spec you would hand the agent.

What you know:

  • Node 20, Express, Postgres and the official stripe package
  • orders live in an orders table keyed by your own order_id, and each Checkout Session carries it in metadata.order_id
  • the webhook signing secret is in the STRIPE_WEBHOOK_SECRET environment variable
  • fulfillment means emailing the warehouse, which is slow and sometimes fails

Then, in a few sentences: what would a bare "write me a Stripe webhook" prompt get wrong?