Square Production Webhooks Returning 401 — Signature Mismatch

Questions
1

All our Square Production webhooks return 401, including real payments, refunds, and test events.

We’ve verified the signing key, notification URL, raw request body, and HMAC-SHA256 implementation. Everything appears correct, but signature verification still fails.

Has anyone experienced this or know what else could cause it?

3

Hi Loo, Welcome to the Square Developer Forum!

Below is some information about our webhooks that might help you troubleshoot this issue:

  • Each webhook subscription has its own signature key.
  • If your app has more than one subscription, or you’ve recreated one, make sure you’re using the Production key from the exact subscription that sends these events, not a Sandbox key or a key from another subscription.
  • Square signs the notification URL concatenated with the raw body.
  • The URL in your HMAC input has to match the subscription’s notification URL character for character, including scheme, host, path, trailing slash and query string.
  • If a load balancer, proxy or framework rewrites the host, scheme or path, use the configured URL as a constant instead of rebuilding it from the incoming request.
  • Compare your result, Base64-encoded, against the x-square-hmacsha256-signature header, not the legacy x-square-signature header.

Square’s SDKs include a WebhooksHelper.isValidWebhookEventSignature helper. If it also fails with your key and URL, reply with your application ID and subscription ID

4

Thanks for the guidance. We completed the verification using Square’s official SDK against a real Production webhook.

Results:

  • WebhooksHelper.isValidWebhookEventSignature (SDK 39.1.1): false

  • WebhooksHelper.verifySignature (SDK 46.0.0): false

  • Our own HMAC-SHA256 verification: false

Production details:

  • Application ID: sq0idp-cs7CFaDsxPYmYx8ria3SFw

  • Subscription ID: wbhk_ba850f4db7fb4183a5767f372941afca

  • Event ID: df8f4677-e221-36c4-8913-de451d1d3973

  • Event type: payment.created

  • Received: October 16, 2026, 12:52:52 UTC

The captured subscription header matches our Production subscription, and we’ve manually verified that the configured signing-key fingerprint matches the key displayed for that subscription.

We used the exact registered notification URL, original captured body without JSON reserialization, and the x-square-hmacsha256-signature header. The body length also matches Content-Length.

Despite this, both official Square helpers reject the signature. This happens with real Production notifications and simulated test events.

Could your engineering team investigate the signing-side records for this event and confirm which subscription, notification URL, and signing key were used? We’d also appreciate confirmation that no legacy subscription is involved.

We’ve kept signature verification enabled and haven’t changed our webhook configuration or payment flows.

If additional sensitive diagnostic information is needed, please let us know how to provide it privately.

5

Hello, any help here?

6

Hi Loo,

I sent you a DM requesting more information to help figure this out

7

thank you, ive replied back with the details