How to Validate the HMAC Hash in Kong Gateway for Shopify Webhooks

When integrating Shopify webhooks with Kong Gateway, one common challenge is validating the HMAC signature provided by Shopify. At the time of writing, there is no built-in Kong plugin that can directly read and validate the HMAC value passed in the X-Shopify-Hmac-Sha256 header. Shopify does not allow customizing this header to use Kong’s standard HMAC auth plugin , which expects the signature in the Authorization header.

To solve this, I created a custom Kong plugin that reads the HMAC value from the X-Shopify-Hmac-Sha256 header and validates it against the raw request body using your Shopify shared secret. You can find the plugin here:
👉 https://github.com/ajavedm/kong-plugin-shopify-hmac

Why Do We Need This Plugin?

Shopify webhooks include an X-Shopify-Hmac-Sha256 header containing a base64-encoded HMAC signature of the raw request body. This signature ensures the webhook payload is authentic and untampered. To verify it:

Compute the HMAC SHA256 hash of the raw request body using your Shopify app’s shared secret.
Compare the computed hash with the value in the X-Shopify-Hmac-Sha256 header.

Kong’s built-in hmac-auth plugin cannot handle this because:

It expects the signature in the Authorization header.
It does not support Shopify’s specific webhook format.

About the Plugin

This custom plugin (shopify-hmac-auth) was built following Kong’s official standards:
https://developer.konghq.com/custom-plugins/get-started/set-up-plugin-project/

Key Features

Validates HMAC signature from X-Shopify-Hmac-Sha256 header.
Uses the raw request body for signature computation.
Rejects requests with missing or invalid signatures.
Lightweight and fast.
Works with both DB-less and DB-backed Kong deployments.

The plugin was tested using:

How Shopify Webhooks Work

Shopify sends webhooks with the following characteristics:

Header: X-Shopify-Hmac-Sha256 → Base64-encoded HMAC SHA256 signature.
Body: Raw JSON payload of the event.
Expectation: A 200 OK response within 5 seconds. If not, Shopify retries up to 8 times over 4 hours. Failure to respond may result in webhook subscription deletion.

Best Practices for Handling Shopify Webhooks

Respond Quickly
Always return a 2XX status immediately to avoid timeouts. Heavy processing should be done asynchronously.
Use Queues for Processing
Offload webhook data to a queue system like:
- Azure Service Bus
- Amazon SQS
- RabbitMQ
- Kafka
Or use lightweight libraries like https://www.npmjs.com/package/better-queue for Node.js.
Ensure Data Integrity
Validate the HMAC signature before processing to prevent spoofed requests.

Shopify Webhook → sends HTTP POST with payload and X-Shopify-Hmac-Sha256 header
Kong Gateway → validates HMAC signature, forwards request if valid
App Service API → responds quickly with 200 OK, publishes message to RabbitMQ
RabbitMQ → queues message for asynchronous processing
Worker → consumes message from RabbitMQ and performs heavy processing

How the Plugin Works

Here’s the high-level flow:

Extract the X-Shopify-Hmac-Sha256 header.
Compute HMAC SHA256 of the raw request body using your Shopify secret.
Compare the computed hash with the header value.
If valid → Forward the request.
If invalid → Reject with 401 Unauthorized.

Installation & Usage

Clone the plugin repository:

git clone https://github.com/ajavedm/kong-plugin-shopify-hmac.git

Follow Kong’s custom plugin installation guide:
https://developer.konghq.com/custom-plugins/get-started/set-up-plugin-project/

Enable the plugin in your Kong configuration:

plugins:
  - name: shopify-hmac-auth
    config:
      secret: <your-shopify-shared-secret>

Conclusion

Shopify’s webhook security model relies on HMAC validation, and Kong Gateway is a great place to enforce this. Since Shopify does not allow customizing headers for Kong’s built-in HMAC plugin, this custom solution bridges the gap.

👉 https://github.com/ajavedm/kong-plugin-shopify-hmac
👉 https://shopify.dev/docs/apps/build/webhooks/subscribe/https