A customer clicks a purchase button, the application sends a request, and the connection fails before a response arrives. The startup now faces an uncomfortable question: did the operation fail, or did it succeed while the response was lost?
Repeating the request blindly can create duplicate work. Refusing to repeat it can leave a legitimate customer stuck.
A reliable payment integration needs an explicit retry policy. Idempotency keys and webhook handling solve different parts of that problem.
Give each intended operation a stable identity
Stripe documents idempotency keys as a way to retry supported requests without accidentally performing the same operation twice. The client supplies a key that identifies retries of the same intended request.
For a startup, the key design question is what counts as one operation.
A customer trying to complete the same purchase after a connection error should not automatically become a new purchase merely because another HTTP request was sent. Conversely, a deliberate second order should not accidentally reuse the identity of the first.
Store the operation’s identity alongside the application’s own record. This makes it possible to explain what happened when a customer contacts support.
Respect the provider’s exact semantics
Stripe’s API v1 documentation says that the first result is saved after endpoint execution begins, and retries with the same key return that saved result, including some error responses. It also checks that reused keys carry matching parameters and documents a retention boundary. API v2 has different retry semantics.
The practical implication is that “we use idempotency” is not a complete design description.
The team should know which API behavior applies, when a retry is appropriate, and when reconciliation is required. A changed request should not be disguised as a retry of an earlier operation.
Avoid treating a provider’s temporary key retention as a permanent business ledger. The application still needs durable records of its own orders and outcomes.
Handle incoming notifications independently
Webhook delivery introduces another boundary. Stripe states that events can arrive more than once and are not guaranteed to arrive in generation order. Its guidance recommends tracking processed event identifiers to recognize duplicate deliveries.
This means an idempotent outgoing request does not automatically make the incoming event handler safe.
Consider an order-fulfillment process. Receiving the same payment event again should not create a second shipment. That business action needs its own protection.
Likewise, the handler should not depend on a perfect event sequence. It should be able to consult the relevant object state when information is missing.
Test interruptions as product scenarios
Before launch, rehearse a small set of failures: a lost response, a repeated click, a duplicate webhook, and events arriving in an unexpected order.
Define the expected customer-visible result for each case. The customer should see a clear pending or completed state rather than contradictory messages from separate parts of the application.
Verify webhook signatures using the provider’s documented method. Stripe’s guidance requires the raw request body for its signature-verification process.
Keep operational records that let support staff connect a customer’s order with the external request and notification history, without exposing secrets.
A startup does not need a large engineering team to establish these rules. It needs a clear definition of one purchase, a documented response to uncertainty, and tests that prove retries do not become duplicate business actions.
