Payments & Fintech

Idempotency and Webhooks in Payment Integrations

How idempotency keys and verified, deduplicated webhooks prevent double charges and missed updates in payment integrations, with a practical checklist.

By Devacon LtdPublished 5 min read

Networks fail at the worst moments. A request to create a payment times out: did the charge go through or not? A webhook announcing a successful payment arrives twice, or arrives before the event that should have come first. In most software, a duplicate or out-of-order message is an annoyance. In payments, it can mean charging a customer twice or shipping an order that was never paid for.

Two techniques handle most of this: idempotency on the requests you send, and careful webhook handling for the events you receive. This article uses Stripe’s documentation as a worked example, because it is explicit about the behavior, and points to the emerging IETF standard. Other gateways have their own mechanisms, so always confirm the details in your provider’s documentation.

Idempotency: making retries safe

An operation is idempotent if doing it twice has the same effect as doing it once. In HTTP, some methods, such as GET, PUT and DELETE, are defined as idempotent. POST, which most payment APIs use to create charges, is not. Idempotency keys fill that gap.

How an idempotency key works

The client generates a unique key for each logical operation and sends it with the request, usually in an Idempotency-Key header. If the client retries with the same key, the server recognizes the retry and returns the original result instead of performing the operation again.

Stripe’s API reference documents its behavior in detail:

  • All POST requests in its v1 API accept idempotency keys. Sending one with GET or DELETE has no effect, because those requests are already idempotent.
  • Stripe suggests V4 UUIDs, or another random string with enough entropy to avoid collisions. Keys can be up to 255 characters, and Stripe advises against using sensitive data such as email addresses as keys.
  • For v1, Stripe saves the status code and body of the first request made with a key once the endpoint starts executing, and returns that saved response for retries, including 500 errors.
  • If incoming parameters fail validation, or the request conflicts with one already executing, no result is saved and the request can be retried.
  • Reusing a key with different parameters produces an error, to prevent accidental misuse.
  • Keys can be removed after they are at least 24 hours old; a key reused after it has been pruned is treated as a new request.

The emerging standard

The IETF HTTPAPI working group is standardizing this pattern in an Internet-Draft, The Idempotency-Key HTTP Header Field. The most recent version at the time of writing is draft 08, dated 22 October 2026. It is a draft, not yet an RFC, and could still change. It targets non-idempotent methods such as POST and PATCH, recommends a UUID or similar random identifier, and describes error responses for a missing key (400), a key reused with a different payload (422) and a retry that arrives while the original is still processing (409).

Practical rules for idempotency keys

  • Generate the key once per business operation, such as “pay order 1234”, and store it with the order before sending the request. A key generated fresh on each retry defeats the purpose.
  • Retry with the same key and the same parameters after timeouts and connection errors.
  • Treat a saved error as an answer. If the provider replays a stored failure, retrying with the same key will not change it; investigate, and use a new key only for a genuinely new attempt.
  • Apply the same idea to your own APIs. If your mobile app or partner calls your endpoints to create orders or payments, accept idempotency keys there too.

Webhooks: receiving events reliably

Payment providers use webhooks to tell your system about things that happen asynchronously: a bank confirms a payment, a customer disputes a charge, a subscription renews. Stripe’s webhook documentation sets out several behaviors your handler must expect.

Verify that the event is genuine

Without verification, anyone who finds your endpoint can send fake “payment succeeded” events. Stripe signs each event with an HMAC-SHA256 signature in the Stripe-Signature header, computed over a timestamp and the raw request body using a per-endpoint secret. Its documentation stresses three details:

  • Use the raw body. If your framework parses or reformats the body before verification, the signature check fails.
  • Compare signatures in constant time, and ignore signature schemes other than the current one, to prevent downgrade attacks.
  • Check the timestamp. Stripe’s libraries default to a five-minute tolerance to limit replay attacks, and the documentation warns that a tolerance of zero disables the recency check entirely.

Stripe also recommends rolling signing secrets periodically and accepting events only from its published IP addresses.

Expect duplicates and disorder

Stripe states that an endpoint might occasionally receive the same event more than once, and that events are not necessarily delivered in the order they were generated. Its advice is to log the event IDs you have processed and skip ones already seen, and not to rely on timestamps to decide order. Where your logic needs the latest state, fetch the object from the API rather than trusting the order of arrival.

Respond fast, process later

Your endpoint should return a 2xx status quickly, before any slow work, or the delivery may time out and be retried. Stripe recommends processing events through an asynchronous queue so that spikes in deliveries do not overwhelm your servers. In live mode, Stripe retries failed deliveries for up to three days with exponential backoff.

Putting it together

Concern Technique
Request timed out; did it succeed? Retry with the same idempotency key
Same webhook delivered twice Record processed event IDs and skip repeats
Events arrive out of order Fetch current object state; design handlers to be order-independent
Fake events Verify signatures on the raw body; check timestamps
Slow handlers cause retries Acknowledge quickly; process from a queue
Missed events during an outage Reconcile against the provider’s API on a schedule

Implementation checklist

  • Store an idempotency key with every payment-creating operation before the first attempt.
  • Wrap provider calls in a retry policy with backoff that reuses the stored key.
  • Verify every webhook signature against the unmodified body, with a sensible timestamp tolerance.
  • Make webhook processing idempotent: a unique constraint on event ID in your database is a simple guard.
  • Subscribe only to the event types you need.
  • Exempt the webhook route from CSRF middleware, as Stripe notes frameworks may otherwise reject it, while keeping signature checks in place.
  • Add a scheduled reconciliation job that compares your records with the provider’s, to catch anything missed.
  • Test the unhappy paths: duplicate deliveries, reversed order, invalid signatures and provider timeouts.

How Devacon can help

We build payment gateway integrations with idempotent request handling, verified webhook processing and reconciliation jobs, and we test them against duplicate, delayed and out-of-order events. A typical engagement covers the integration, its failure-path tests and monitoring for stuck or missing payments. Learn more about our fintech integration services.

Sources

  1. Stripe API reference: Idempotent requests
  2. Stripe documentation: Receive Stripe events in your webhook endpoint
  3. IETF Internet-Draft: The Idempotency-Key HTTP Header Field (draft-ietf-httpapi-idempotency-key-header)
  4. RFC 9110: HTTP Semantics

Facts in this article were checked against the sources above on November 17, 2026. Standards and products change, so check the source before relying on a detail. Related service: Fintech Integrations.

More insights

Let's build something great together

Ready to talk about custom software? Tell us about your project requirements and we will get back to you.