1. What webhooks are
A webhook is an automated message that Shopify sends to your app when a specific event happens in a store. Instead of your app constantly polling Shopify — "any new orders? any new orders now?" — Shopify pushes a notification to a URL you control the instant the event occurs.
This is what makes apps feel real-time. When a customer places an order and your loyalty app instantly awards points, that's a webhook: Shopify sent your app an orders/create notification, and your app reacted. When a merchant uninstalls your app and your app cleans up their data, that's the app/uninstalled webhook firing.
Webhooks are the event-driven backbone of Shopify apps. Polling the API for changes would be slow, inefficient, and rate-limited; webhooks deliver events as they happen, which is both faster and far more efficient.
The core idea: webhooks invert the usual request flow. Normally your app asks Shopify for data (pull). With webhooks, Shopify tells your app when something happened (push). This is why webhooks are essential for any app that needs to react to store activity — order processing, inventory sync, loyalty points, subscription events.
2. How webhooks work
The mechanics are straightforward once you see the flow:
- You subscribe to a topic. A topic is an event type, like
orders/createorcustomers/update. You tell Shopify which topics you care about and what URL to send them to. - The event happens. A customer places an order, updates their profile, etc.
- Shopify sends an HTTP POST to your destination URL, with the event data as a JSON payload in the request body and several headers identifying the topic, the shop, and the HMAC signature.
- Your app verifies and processes it. Your endpoint checks the HMAC (to confirm it's really from Shopify), then acts on the payload — awarding points, syncing inventory, whatever the app does.
- Your app responds 200. A quick 200 status tells Shopify the webhook was received. Errors or slowness trigger retries.
The destination must be a publicly accessible HTTPS endpoint. During development you'll often use a tunneling tool so Shopify can reach your local server; in production it's your deployed app's URL.
3. Common webhook topics
Shopify offers webhook topics for a wide range of events. The ones apps use most:
| Topic | Fires when | Typical use |
|---|---|---|
orders/create | An order is placed | Award points, sync, fulfill |
orders/updated | An order changes | Update records, recalculate |
orders/fulfilled | An order ships | Trigger review requests |
customers/create | A customer is added | Enroll in loyalty, sync CRM |
customers/update | A customer changes | Keep app data in sync |
products/update | A product changes | Reindex, update bundles |
app/uninstalled | Merchant removes the app | Stop billing, flag cleanup |
app_subscriptions/update | Subscription status changes | Activate/deactivate features |
You subscribe only to the topics your app needs. A loyalty app needs orders/create and the customer topics; a review-request app needs orders/fulfilled; every app needs app/uninstalled and the three mandatory compliance topics.
4. HMAC verification — the critical step
Because your webhook endpoint is a public URL, anyone could send a POST to it pretending to be Shopify. HMAC verification is how you confirm a webhook genuinely came from Shopify and wasn't forged or tampered with. Skipping it is a serious security hole and an App Store review failure.
How it works
Every webhook Shopify sends includes an X-Shopify-Hmac-Sha256 header containing a signature. Shopify computes this signature by running HMAC-SHA256 over the raw request body using your app's shared secret. To verify:
- Take the raw, unparsed request body (this matters — parsing and re-serializing changes the bytes and breaks the check).
- Compute HMAC-SHA256 of that body using your app's secret.
- Compare your computed signature to the value in the
X-Shopify-Hmac-Sha256header, using a constant-time comparison. - If they match, the webhook is authentic. If not, reject it with a 401.
The single most frequent mistake is verifying HMAC against the parsed body instead of the raw bytes. Many web frameworks parse JSON before your handler runs, and re-serializing produces different bytes than Shopify signed — so the HMAC never matches. You must capture the raw request body before any parsing for verification to work.
5. The mandatory GDPR webhooks
Beyond the event webhooks you choose, every Shopify app must implement three compliance webhooks related to data privacy. These are required for App Store listing and are checked in review — and missing them is the single most common rejection reason.
| Webhook | Fires when | You must |
|---|---|---|
customers/redact | A customer requests data deletion | Delete that customer's data |
shop/redact | 48 hours after a store uninstalls | Delete all that store's data |
customers/data_request | A customer requests their data | Provide the data you hold |
These must be implemented even if your app stores no customer data — the endpoints have to exist, verify HMAC, and return 200. They're configured through your app configuration file or the Partner Dashboard. For the full compliance picture, see the GDPR & compliance guide.
6. Configuring webhooks
There are three ways to subscribe to webhooks, used in different situations:
App configuration file (declarative)
You declare webhook subscriptions in your app's shopify.app.toml configuration file. This is the standard approach for the mandatory compliance webhooks and for topics every install needs. The subscriptions are applied when the app is deployed — declarative and version-controlled.
Partner Dashboard
You can configure the mandatory compliance webhook endpoints in the Partner Dashboard's app settings. This is a common place to set the GDPR webhook URLs.
Admin API (programmatic)
You can create webhook subscriptions dynamically through the Admin API (GraphQL webhookSubscriptionCreate or the REST equivalent). This is useful when subscriptions need to be created per-install at runtime or adjusted based on app state, rather than being the same for every merchant.
Most apps use a combination: declarative config for the universal and compliance webhooks, and the API for any dynamic, per-merchant subscriptions.
7. Reliability — retries, speed, and idempotency
Webhooks are reliable but not guaranteed-exactly-once. Building robust webhook handling means accounting for three realities:
Respond fast
Shopify expects a 200 response within a few seconds (around 5). If your processing is heavy, don't do it inline — acknowledge the webhook immediately with a 200, then process asynchronously (queue a background job). A slow handler causes timeouts, which Shopify treats as failures.
Handle retries and duplicates
If your endpoint fails or times out, Shopify retries the delivery over a window with backoff. This means your handler can receive the same webhook more than once. Your processing must be idempotent — processing the same event twice should not double-award points or create duplicate records. Use the event's identifiers to detect and skip duplicates.
Don't rely on webhooks alone for critical data
Webhooks can occasionally be missed (extended outages, edge cases). For critical data, supplement webhooks with periodic reconciliation via the API — a scheduled job that catches anything missed. Webhooks handle the real-time path; reconciliation is the safety net.
The most damaging webhook bug in production is non-idempotent processing. Because Shopify retries, a loyalty app that awards points on every orders/create delivery — without deduplicating — will over-award points when a webhook is retried. Always make webhook processing idempotent by keying on the event or resource ID.
8. How AI builders handle webhooks
Webhooks involve several things that are easy to get wrong: HMAC verification against the raw body, the three mandatory GDPR endpoints, fast acknowledgment with async processing, and idempotent handling of retries. This is exactly the layer where DIY and generic-AI apps fail — they skip HMAC verification, omit the compliance webhooks, or process non-idempotently.
A Shopify-specific builder like Shopivibe generates webhook handlers with HMAC verification, the three mandatory GDPR endpoints, and proper acknowledgment patterns by default. When you describe an app that needs to react to orders, the correct orders/create subscription and handler are generated — with the security and compliance pieces included, not bolted on later.
You still own and can extend the handlers. But you start from a webhook setup that verifies signatures, satisfies Shopify's mandatory compliance requirements, and won't fail App Store review on the most common rejection reason.