Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

APIs and integrations

Stripe vs Adyen API Idempotency Keys and Webhook Verification, Side by Side

In short

Both accept a client-generated key on POST requests, but Stripe keeps keys at least 24 hours and Adyen 7 to 14 days. Stripe signs the raw body with a timestamp in a header; Adyen's standard webhooks sign eight chosen fields inside the JSON. Stripe retries events for up to three days, Adyen from a retry queue for up to 30.

How is the idempotency key sent, and how long does each vendor keep it?

Both vendors take the key in a request header on POST requests. They differ on length, lifetime and scope, and those three details decide how you generate and store keys.

A key that fits Adyen's 64-character limit also fits Stripe's. If one code path serves both, generate the shorter key. Adyen documents GET, DELETE and PUT as idempotent by definition, and Stripe says keys on GET and DELETE have no effect.

DetailStripe (API v1)Adyen
Header`Idempotency-Key``idempotency-key`
Maximum length255 characters64 characters
Suggested formatV4 UUID or another high-entropy random stringV4 UUID
How long it is keptKeys may be removed once they are at least 24 hours oldValid for 7 to 14 days after first submission
ScopeNot stated on the pageStored per company account; not checked across regional endpoints

Checked against: source 1, source 2

What happens when a key is replayed, reused with other data, or still in flight?

On Stripe API v1, the status code and body of the first request are saved once execution begins. A retry with the same key returns that saved response, including a 500. Stripe compares the incoming parameters with the original and returns an error if they differ. If validation fails, or the request collides with one still running, nothing is saved, so you may retry.

On Adyen, a replay returns the response to the first attempt without a second operation. A duplicate that arrives before the first finishes gets 422 or 409 with error code 704. A transient-error: true header marks it as retryable with the same key; without it, Adyen says not to retry.

What Adyen does when the same key arrives with a different body is not documented on the page I read. I would not rely on either behaviour there. Treat a key as bound to one exact request on both platforms.

Stripe also describes a different rule for its v2 API, where retries finish failed work instead of returning a saved response. This page covers v1 only.

Checked against: source 1, source 2

Where is the webhook signature, and what exactly is signed?

Stripe puts it in the Stripe-Signature header as t= and one or more v1= entries. The v1 value is an HMAC with SHA-256 over the timestamp, a dot and the unmodified request body, using the endpoint's whsec_ secret. Because the raw bytes are signed, a framework that parses and re-serializes the body breaks verification. See the Stripe signature fix page for that failure.

Adyen's standard webhooks carry hmacSignature inside additionalData in the JSON. It is a Base64 HMAC-SHA256, and the signed string is not the body. It is eight fields joined with colons: pspReference, originalReference, merchantAccountCode, merchantReference, value, currency, eventCode and success, with empty values left as empty strings.

Some other Adyen webhooks, such as recurring token lifecycle events, send hmacsignature and protocol as request headers and sign the raw body, which Adyen says not to deserialize first. So an Adyen integration may need two verification paths.

Checked against: source 3, source 6

Does either vendor protect against replayed webhooks?

Stripe signs a timestamp into every delivery, and its libraries reject deliveries more than 5 minutes off by default. A tolerance of 0 disables the check. Each retry gets a fresh timestamp and signature.

The Adyen HMAC page does not mention a timestamp or a replay window, so a timestamp check is not something I can recommend from Adyen's documents. Its duplicate guidance is the tool they do give you, covered below.

Checked against: source 3, source 6

How do delivery and retries differ?

Both want a quick 2xx before any business logic. Adyen gives a number: respond within 10 seconds or the webhook is marked Failing. Stripe's page names timeouts as a failure cause but gives no figure.

BehaviourStripeAdyen
Automatic retriesUp to three days with exponential backoff in live mode; three tries over a few hours for sandbox eventsA few immediate retries, then a retry queue for up to 30 days
Published scheduleNoYes: 30 s, 30 s, 1 m, 2 m, 5 m, 10 m, 15 m, 30 m, 1 h, 2 h, 4 h, 8 h
Manual resendDashboard up to 15 days; CLI up to 30 daysRetry or Ignore in the Customer Area
RedirectsCounted as failuresEndpoint must be reachable without redirects
Secret rotationOld secret can stay active up to 7 daysKeep accepting the previous key "for some time"

Checked against: source 3, source 4, source 5

How should I handle duplicates and ordering?

Stripe does not guarantee event order and says to track event IDs. Two distinct events can describe the same thing, so it suggests matching on the data.object ID plus the event type.

Adyen duplicates share eventCode and pspReference, while eventDate and other fields can differ. Adyen says to use the latest one, and to check the timestamp, plus sequenceNumber where present, for order.

So the dedupe key differs. On Stripe it is the event ID. On Adyen it is the pair of event code and PSP reference, and the newest copy wins instead of the first.

Checked against: source 3, source 4

What is not documented?

Adyen's pages I read do not say how a reused key with a changed body is handled, or give a replay window for webhooks. Stripe's page gives no handler timeout in seconds.

This page leaves out Stripe's v2 idempotency, thin events, Adyen's other webhook formats, IP allowlisting, fees and any business comparison.

Checked against: source 2, source 3, source 4, source 5

What else do people ask?

Should I reuse the same idempotency key across Stripe and Adyen?

You can generate one V4 UUID per logical operation and send it to either vendor. Keep the key scoped to one exact request, and remember Adyen's 64-character limit.

Can I verify an Adyen webhook from the raw body like a Stripe one?

Only for the webhooks that put the signature in a header. For Adyen's standard webhooks the signed string is built from eight fields in the JSON.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. This page compares Stripe and Adyen documents fetched on 19 Nov 2026. I did not run either system for it, so nothing here is a test result. It does not cover fees, business fit, Stripe v2 or thin events, or any Adyen behaviour the pages leave undocumented. Found a mistake? Tell me.

Keep reading

Next step

Have a project in mind?

Tell me about it. A discovery call within 48 hours.