Typical Webhook Signature Verification Error (Shopify + Laravel)
When middleware consumes the raw HTTP stream, JSON gets re-serialized before hashing, or encoding/prefixes mismatch in Shopify + Laravel, your server logs an exception matching the output below:
HTTP 401 Unauthorized: Shopify HMAC mismatch — omitted 4th parameter ($binary = true) in PHP hash_hmac() before calling base64_encode().
Raw Request Stream Handling & Replay Protection in Shopify + Laravel
Building a Shopify Public App or custom store integration in Laravel 11 or 12 requires passing Shopify's strict HMAC verification checks; including automated Shopify App Store security audits that intentionally send forged X-Shopify-Hmac-Sha256 headers and reject apps that fail to return HTTP 401 Unauthorized.
The #1 PHP bug on Shopify webhooks is forgetting the fourth boolean argument ($binary = true) in hash_hmac("sha256", $rawBody, $secret, true). By default, PHP's hash_hmac() returns a 64-character lowercase hex string. Passing that hex string into base64_encode() produces an 88-character Base64 string instead of Shopify's expected 44-character Base64 encoding of the raw 32-byte digest.
Second, you MUST pass $request->getContent() directly into hash_hmac(); never json_encode($request->all()), which mutates whitespace, escapes forward slashes, and turns floating-point strings into numbers. Third, register your Shopify webhook endpoints in routes/api.php (or exclude webhooks/shopify/* in bootstrap/app.php) so Laravel's CSRF middleware never blocks Shopify with HTTP 419.
Because Shopify drops webhook subscriptions after repeated 5-second timeouts, validate X-Shopify-Hmac-Sha256 inside dedicated VerifyShopifyWebhook middleware, deduplicate via Cache::add("shopify_wh:{$webhookId}", ..), dispatch a queued Laravel Job onto Redis, and respond 200 OK immediately.
Use the interactive browser Web Crypto debugger above to test exact Shopify Base64 headers, inspect the Hex vs. Base64 mismatch diagnostic, and copy the production-ready Laravel controller snippet.
For Laravel Shopify apps serving dozens or thousands of merchant stores, pairing VerifyShopifyWebhook middleware with a fast Redis queue connection ensures order/create and inventory/update spikes never trigger Shopify's 5-second timeout or automatic webhook deletion. Write a PHPUnit feature test posting raw multi-line JSON with call("POST", .., [], [], [], headers, $rawJson) to lock in binary Base64 verification across future Laravel upgrades.
Step-by-Step Shopify + Laravel Webhook Verification Setup
Follow each step below to preserve untouched raw request bytes, enforce constant-time HMAC verification, and offload webhook jobs asynchronously for fast 2xx acknowledgments.
1Build VerifyShopifyWebhook Middleware Using Binary hash_hmac()
app/Http/Middleware/VerifyShopifyWebhook.phpPass true as the fourth argument to hash_hmac() so PHP returns raw binary bytes before base64_encode(), then compare using hash_equals().
app/Http/Middleware/VerifyShopifyWebhook.phpphp<?php namespace App\Http\Middleware; use Closure; use Illuminate\Http\Request; use Symfony\Component\HttpFoundation\Response; class VerifyShopifyWebhook { public function handle(Request $request, Closure $next): Response { $hmacHeader = (string) $request->header('X-Shopify-Hmac-Sha256', ''); $secret = (string) config('services.shopify.webhook_secret'); if ($hmacHeader === '' || $secret === '') { return response('Unauthorized', 401); } // CRITICAL: 4th parameter true outputs raw binary bytes required by Shopify Base64 $calculated = base64_encode( hash_hmac('sha256', $request->getContent(), $secret, true) ); if (! hash_equals($calculated, $hmacHeader)) { return response('Invalid Shopify HMAC', 401); } return $next($request); } }2Dispatch Queued Fulfillment Jobs and Return 200 OK Within 5 Seconds
app/Http/Controllers/ShopifyWebhookController.phpCheck X-Shopify-Webhook-Id for idempotency and dispatch heavy Shopify API or order sync tasks onto your Redis queue worker.
app/Http/Controllers/ShopifyWebhookController.phpphp<?php namespace App\Http\Controllers; use App\Jobs\ProcessShopifyWebhook; use Illuminate\Http\Request; use Illuminate\Http\Response; use Illuminate\Support\Facades\Cache; class ShopifyWebhookController extends Controller { public function __invoke(Request $request): Response { $webhookId = (string) $request->header('X-Shopify-Webhook-Id', ''); $topic = (string) $request->header('X-Shopify-Topic', ''); $shop = (string) $request->header('X-Shopify-Shop-Domain', ''); if ($webhookId !== '' && ! Cache::add("shopify_wh:{$webhookId}", true, now()->addDay())) { return response('Duplicate ignored', 200); } ProcessShopifyWebhook::dispatch($topic, $shop, $request->json()->all()); return response('OK', 200); } }3Configure Shopify Secret in config/services.php
config/services.phpStore SHOPIFY_WEBHOOK_SECRET in config/services.php so php artisan config:cache never causes env() to return null in production.
config/services.phpphp'shopify' => [ 'webhook_secret' => env('SHOPIFY_WEBHOOK_SECRET'), ],4Register Shopify Webhook Endpoints in routes/api.php
routes/api.phpAttach VerifyShopifyWebhook middleware to all order and mandatory GDPR compliance endpoints.
routes/api.phpphpuse App\Http\Controllers\ShopifyWebhookController; use App\Http\Middleware\VerifyShopifyWebhook; use Illuminate\Support\Facades\Route; Route::post('/webhooks/shopify/{topic}', ShopifyWebhookController::class) ->middleware(VerifyShopifyWebhook::class);
Common Shopify + Laravel Webhook Pitfalls
Avoid these three subtle production failure modes when verifying external webhook signatures.
Forgetting the 4th Argument (true) in PHP hash_hmac()
Calling base64_encode(hash_hmac("sha256", $raw, $secret)) without true Base64-encodes a hex string instead of binary bytes; guaranteed 401 failure on every Shopify request.
Returning 403 or 400 Instead of 401 on Invalid Shopify Compliance Webhooks
Shopify's automated App Store submission checks specifically assert HTTP 401 Unauthorized when sending an invalid X-Shopify-Hmac-Sha256 header to GDPR compliance endpoints.
Laravel TrimStrings Middleware Not Affecting getContent()—But Breaking $request->all()
Laravel's global TrimStrings and ConvertEmptyStringsToNull middleware mutate $request->all() inputs. Always hash $request->getContent() (the raw stream) before touching parsed arrays.
Audit Your Webhook Signing Secrets & Nginx Reverse Proxy Headers
Make sure your .env signing secret has no trailing spaces or unquoted # truncation and your Nginx proxy forwards raw POST payloads without 301 redirects:
Validate Laravel 11/12 .env files locally in your browser. Fix InvalidFileException, unquoted # in DB_PASSWORD, invalid base64 APP_KEY, and config:cache traps.
Configure Nginx reverse proxy for Laravel Octane (FrankenPHP/Swoole) on port 8000 and Laravel Reverb WebSockets on port 8080 with SSL and 3600s timeouts.
Frequently Asked Questions
- Why does base64_encode(hash_hmac("sha256", ..)) return 88 characters instead of 44 in PHP?
- You omitted the 4th parameter ($binary = true). Without true, hash_hmac() outputs 64 ASCII hex chars, which Base64-encode to 88 chars. Adding true outputs 32 raw bytes, which Base64-encode to Shopify's exact 44-character header.
- Does Shopify send X-Shopify-Hmac-Sha256 on GDPR compliance webhooks too?
- Yes. customers/data_request, customers/redact, and shop/redact all require identical X-Shopify-Hmac-Sha256 verification and must return 401 Unauthorized when the HMAC is invalid.
- Why did my Laravel Shopify webhook pass locally but fail on Forge/Nginx?
- Check that php artisan config:cache is updated with the live Partner App Client Secret, and verify Nginx did not redirect http:// to https:// via 301 on the webhook URL.
- Can I reuse VerifyShopifyWebhook across multiple Shopify stores?
- All stores that install the same Shopify Partner App share your App's single Client Secret. Only custom per-store Admin webhooks require looking up a store-specific secret by X-Shopify-Shop-Domain.
Related Webhook HMAC Verification Guides
Browse all 10 webhook guides →Shopify Base64 HMAC Webhook Verification in Python FastAPI
Fix Shopify X-Shopify-Hmac-Sha256 webhooks in Python FastAPI. Use base64.b64encode on raw digest bytes, await request.body(), and hmac.compare_digest.
Stripe Webhook Signature Verification in Laravel (Raw Body & CSRF Fix)
Fix Stripe SignatureVerificationException in Laravel 11/12 using $request->getContent(), CSRF exclusion in bootstrap/app.php, hash_equals, and async queues.
GitHub Webhook X-Hub-Signature-256 Verification in Laravel (Queues & Raw Body)
Verify GitHub X-Hub-Signature-256 webhooks in Laravel 11/12 using $request->getContent(), hash_equals(), CSRF bypass, and async Redis queue job dispatch.
ASP.NET Core 8/9 Raw Body Webhook HMAC Verification (EnableBuffering Guide)
Verify Stripe, GitHub, and Shopify HMAC-SHA256 webhooks in ASP.NET Core 8/9 using EnableBuffering(), StreamReader, and FixedTimeEquals in C#.