Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

My site rejects Adyen notifications because the HMAC check fails

Short answer

Adyen signs each notification with a key that belongs to one webhook endpoint, and your site recomputes the signature to check it. It fails when the key is for another endpoint or for test instead of live, the fields are joined in the wrong order, or a body was changed. Adyen requires a 2xx reply to accept the message.

  • Written for business owners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Does this sound like your situation?

  • Customers pay but my site shows the order as unpaid.
  • It worked in test and stopped when I went live.
  • My developer says the HMAC or signature is invalid.
  • It broke after someone regenerated a key in the Adyen dashboard.
  • Some notification types work and others are rejected.

Why does this happen?

  1. The key belongs to one endpoint

    Adyen states that each HMAC key is tied to one webhook endpoint, so each endpoint needs its own key. You also need a new key when you move from test to live. A site holding the test key checks live messages and rejects them all.

  2. The signed text is built from specific fields

    For standard notifications Adyen documents the fields that are joined with colons, in a fixed order: the PSP reference, original reference, merchant account, merchant reference, amount value, currency, event code and success. Empty fields must stay as empty strings. A different order, or leaving out an empty field, gives a different signature.

  3. Some notifications are signed differently

    Adyen says the signature normally sits in the additional data of the message, but for a few other webhooks it arrives in a request header. For those, the raw body must be used exactly as received, without parsing it first.

  4. A new key takes time to spread

    Adyen notes new keys can take time to propagate and advises accepting events signed with the previous key for a while. Switching the key in your site at the same moment as in the dashboard rejects messages that are still in flight.

  5. A failed reply makes Adyen think delivery failed

    Adyen says each notification must be accepted with a 2xx HTTP status code, and your site should then store and process it. A site that answers with an error because the check failed tells Adyen the message was not received.

What can I do about it today?

  1. Do not turn the check offAsking your developer to skip verification makes the site accept fake payment messages. The check is protection, so it should be fixed, not removed.
  2. Ask which key your live site usesIt must be the key made for the live endpoint, not the test one. Your developer can confirm in a minute.
  3. Do not regenerate keys at randomEach new key can lock out your site until it is updated. Change one only with your developer on hand.
  4. Mark paid orders by checking Adyen firstBefore shipping any order stuck as unpaid, confirm in your Adyen dashboard that the payment succeeded.
  5. Write down when it startedNote whether it followed a go-live, a key change or a site update. This narrows the cause.

When should I bring someone in?

  • Live payments succeed but none of your orders are confirmed.
  • You have orders you cannot match to payments.
  • Nobody is sure which key is in use or who set up the endpoint.

How do I handle it?

  1. Test with Adyen's own sampleI run the sample key and sample notification from Adyen's documentation through your handler to see where it breaks.
  2. Check the key against the endpointI confirm which endpoint and environment each stored key belongs to, without needing the secret itself shown to me.
  3. Fix the check, keep it onThe handler is corrected to build the signed string as documented and to accept the previous key during a change.
  4. Reconcile the missed periodOrders from the failed window are matched against Adyen's records and corrected one by one.

The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.

What do owners ask about this?

Is Adyen at fault?

Usually the message is genuine and your site's check is wrong, for example a key from another endpoint or environment.

Why did it stop at go-live?

Adyen says you need a new key when you switch from test to live, because each key belongs to one endpoint.

Is it safe to skip the check for now?

I advise against it. Without the check, anyone who finds the URL can send a fake paid message.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.

For your developer: the technical fixes

Next step

Want this off your desk?

Send me a few lines on where things stand. I reply within 24 hours.