Stripe checkout webhook: start a paid job once per payment

To act on a Stripe Checkout payment, listen for the checkout.session.completed webhook event, verify its signature on the raw request body, return a 2xx quickly, and fulfill from there. Stripe may deliver the same event more than once, so the step that starts paid work (here, a generation job) must run once per Checkout Session: key it by the session id.

The Stripe facts come from Receive Stripe events in your webhook endpoint and Fulfill orders. The paid job is a Sume Format run, from Create a run and Embed a Format. All were read on 2026-09-29. Sume has no Stripe connector; this is your server calling two HTTPS APIs.

Which Stripe webhook event means the customer paid?

When someone pays, Stripe creates a checkout.session.completed event. Stripe's fulfillment guide says to check the session's payment_status before fulfilling; its sample fulfills when it is not unpaid. Delayed methods such as ACH direct debit and other bank transfers send checkout.session.async_payment_succeeded when the payment succeeds later, so listen for both.

Don't start the job from your success page. Stripe says it's not guaranteed customers visit that page: a customer can pay and lose their connection before it loads.

How do I set up and verify a Stripe checkout webhook?

In practice: verify, save the session id to a queue or table, answer 200, and start the job from a worker.

• Register a public HTTPS endpoint. For local tests, stripe listen --forward-to localhost:4242/webhook forwards events and prints a signing secret.
• Verify each event with Stripe's library, from the raw body, the Stripe-Signature header and the endpoint's whsec_ secret. Any change to the raw body makes verification fail, so keep your framework from parsing it first.
• Stripe's libraries accept a 5-minute gap between the signed timestamp and now by default.
• Return a 2xx quickly, before any complex logic that could cause a timeout. With a success_url set, Checkout waits up to 10 seconds for your response before redirecting the customer.

Why does Stripe send the same checkout event twice?

Because delivery is retried and not exactly-once. Each case below reaches your handler again for a session you may already have fulfilled:

How do I start the job only once per payment?

Build the job's Idempotency-Key from the Checkout Session id, so every repeat lands on the first job. Sume's docs say to derive the key from the thing being made, plus a version you bump when you want a re-run on purpose:

SESSION_ID="cs_test_123"  # from the verified event's data.object
curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stripe-$SESSION_ID-v1" \
  -d '{
    "input": { "product_url": "https://example.com/p/8823" },
    "generation_spend_cap_usd": 3,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

Why does the request body have to stay the same?

Because Sume replays only the same key with the same body: that returns 200 with the original run and idempotency_hit: true, while a changed body is 409 idempotency_conflict and nothing runs. Two copies at the same moment get one run; the loser sees 409 idempotency_key_in_use, which is retryable. Build the body only from stored order data, never from the time or a per-attempt value, and keep the webhook_url fixed; it is part of the body.

Store the returned run id against the order before you mark it fulfilled. Spend caps, key custody and billing your customer are covered in Embed AI video generation in your product; Stripe metered billing for AI video covers charging per job instead of per checkout.