Verify first
Raw-body signature verification rejects forged events before they can reach the order ledger.
Authoritative payment events
Stripe webhook processing that stays correct through retries.
Yito Pay verifies the untouched request body, records each Stripe event once, and moves business work into a retryable queue before any product access changes.
The source of payment truth
A Stripe webhook result, not browser feedback, authorizes fulfillment.
A customer can close a tab after paying, lose connectivity during a redirect, or manufacture a success URL. None of those browser states proves that funds are available. Yito Pay changes an order only after Stripe delivers an event whose signature matches the configured endpoint secret.
The webhook handler reads the raw body before JSON parsing, validates the Stripe-Signature header, and inserts the event ID into the payment schema. Only then does it place the ID on a Cloudflare Queue and return a successful response. Slow work—including subscription retrieval, entitlement updates, and product callbacks—runs outside the request.
This sequence keeps the endpoint fast enough for Stripe while ensuring a valid event cannot disappear between acknowledgement and persistence. It also creates an audit trail for operations without placing card details or secrets in application logs.
Record once
A unique Stripe event ID makes repeat delivery safe and visible instead of surprising.
Work asynchronously
The queue retries processing without forcing Stripe to wait for downstream product systems.
Events arrive on their own schedule
Design for duplicate and out-of-order delivery.
Reliable webhook code does not assume that every event arrives exactly once or in the order a customer experienced it. Yito Pay claims a stored event before processing it, records failures with a concrete message, and permits a timed retry when the earlier worker did not complete.
Order, subscription, refund, dispute, and entitlement changes are independently idempotent. A repeated paid event can confirm the same order, but it cannot create a second order or duplicate the product callback. A subscription update can locate its order by Stripe subscription ID or by the immutable order metadata written at Checkout creation.
- Webhook event IDs have a unique database constraint.
- External product order IDs are unique within an app.
- Event processing is claimed before state mutation.
- Failed claims become eligible for a controlled retry.
- Callback event IDs remain stable across delivery attempts.
Endpoint contract
One production path, several event families.
POST /v1/webhooks/stripe
checkout.session.completed
checkout.session.async_payment_succeeded
invoice.paid
invoice.payment_failed
customer.subscription.updated
refund.updated
charge.dispute.createdThe endpoint is authenticated by Stripe’s signature. It must never sit behind a browser challenge, login page, or CAPTCHA.
State with business meaning
Translate Stripe events into a clear product contract.
Stripe object states are preserved, but products do not need to interpret every Stripe event. Yito Pay turns a confirmed purchase into a signed entitlement.granted callback containing the internal order ID, external order ID, app ID, external user ID, entitlement key, and effective time.
The product verifies the callback timestamp and HMAC signature against its app-specific callback secret. It records the callback event ID before changing access. That final deduplication boundary matters because network retries can happen between Yito Pay and the product just as they can happen between Stripe and Yito Pay.
Refunded or disputed orders can revoke the entitlement; subscription invoices can extend it or mark it past due. The result is a payment pipeline whose decisions can be explained from durable events instead of reconstructed from a customer’s browser history.
Raw bodyused for signature verification
Unique event IDused for webhook deduplication
Signed callbackused for product fulfillment
Questions, answered
Frequently asked questions
Can a Stripe webhook be delivered more than once?
Yes. Yito Pay treats duplicate delivery as an expected condition. It stores the Stripe event ID under a unique constraint and makes downstream order and entitlement changes idempotent.
Why does webhook verification need the raw request body?
Stripe signs the exact request payload. Parsing and reserializing JSON can change bytes and invalidate the signature, so Yito Pay verifies the untouched body before interpreting the event.
Does the checkout success screen grant product access?
No. The success screen can poll and explain progress, but access changes only after a verified Stripe event reaches the order and entitlement pipeline.
Build on a reliable payment boundary
Give every SaaS product one secure way to charge.
Start with the integration guide, then register the app, domain, and server credentials before enabling checkout.