What to Prove in a Shopify Webhook Test
A Shopify webhook test should prove that the subscription is active, the expected topic reaches the correct HTTPS endpoint, the request identifies the intended shop, and the payload shape matches the API version your app supports.
A temporary inspector is useful before application code exists because it exposes the request boundary directly. It does not replace HMAC verification, app authorization, durable queues, or production data controls.
Use a development store and synthetic products, customers, and orders. Shopify webhook payloads can contain personal and commercial data, so do not send live-store events to a public debugging endpoint.
Subscribe to One Topic and Trigger It
Create a temporary endpoint and register it for one topic in a development app or test workflow. Keeping the subscription narrow makes the payload and delivery evidence easier to interpret.
Trigger the corresponding action in the development store, or use an official test facility available to your app workflow. Watch for the incoming request and keep the Shopify app configuration open for comparison.
Remove the temporary subscription when the session ends. A forgotten public endpoint creates unnecessary delivery failures and can expose future test-store data.
- Use a development store with synthetic records
- Subscribe to one topic at a time
- Confirm the callback uses HTTPS
- Delete temporary subscriptions after testing
Inspect Topic, Shop, Version, and Payload
Read X-Shopify-Topic to route the event and X-Shopify-Shop-Domain to identify the tenant. Record the webhook identifier as a correlation and deduplication value, and note the API version header so payload contracts remain traceable.
Compare the JSON body with the topic documentation for the configured API version. Do not assume every topic uses the same object shape, and do not treat optional fields as permanently present.
Preserve raw bytes before JSON parsing. The production receiver needs the original body for HMAC verification, while downstream code should receive a validated typed representation.
Verify HMAC and Handle Duplicates
Shopify signs webhook deliveries. Your application should compute the expected HMAC from the raw request body using the app secret and compare it safely with X-Shopify-Hmac-SHA256 before processing any data.
Reject invalid signatures without exposing secret or digest details. Keep framework body parsing from changing the bytes before verification, and use the official Shopify library for your stack when it provides verified middleware.
Make processing idempotent. Store the webhook identifier or a suitable event key, enforce uniqueness, and make a repeated delivery return success without repeating inventory, fulfillment, email, or billing effects.
Debug Delivery Failures and Go Live Safely
If no request arrives, verify the subscription, topic, callback URL, DNS, TLS, and network routing. If a request arrives but fails, compare the response code and application logs using the webhook identifier.
Keep the HTTP handler short: verify, validate, persist or enqueue, and acknowledge. Process expensive work asynchronously and monitor queue age, failure counts, and repeated delivery attempts.
Before production, test invalid HMAC, malformed JSON, duplicate IDs, an unknown topic, a downstream outage, and safe replay. These cases prove more than a single successful sample delivery.
- Verify HMAC before parsing trusted data
- Route by topic and validate API version assumptions
- Deduplicate before business side effects
- Acknowledge quickly and queue slow work
- Keep live-store data out of public inspectors
Common questions
Frequently asked questions
- How do I test a Shopify webhook?
- Create a temporary HTTPS endpoint, configure a development app or test store subscription for one topic, trigger a test event, and inspect the Shopify topic, shop domain, webhook ID, API version, and JSON body.
- Which Shopify headers should I log?
- Log safe correlation fields such as the webhook ID, topic, shop domain, and API version. Do not log secrets. Preserve the HMAC header only where needed for secure verification diagnostics.
- How is a Shopify webhook HMAC verified?
- Your application computes an HMAC over the raw request body using the app client secret and compares it safely with the X-Shopify-Hmac-SHA256 value. Use Shopify SDK support when available.
- Should a Shopify webhook handler do heavy work inline?
- No. Verify and acknowledge the delivery quickly, then move slower processing to a queue. This reduces timeouts and makes retries and operational recovery easier to control.
Primary sources
Official references
Try it with a real request
Turn the guide into a test.
Open a temporary endpoint, send your payload, and inspect exactly what arrived.
Open the tester