> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Webhooks

> How Upstack uses Shopify webhooks for real-time order, customer, and product updates — which webhooks are registered, what they do, and how to verify they're working.

<Note>
  **Data direction:** This is a **source** — data flows **into** Upstack from this platform for analytics, reporting, and enrichment.
</Note>

Shopify webhooks deliver real-time notifications to Upstack whenever data changes in your store — new orders, customer updates, product modifications, and app lifecycle events. This ensures your Upstack dashboard reflects changes within seconds instead of waiting for periodic API syncs.

## Registered Webhooks

When you install the Upstack Data app, the following webhooks are automatically registered with your Shopify store:

| Webhook Topic      | Fires When                                                        | What Upstack Does                                                |
| ------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------- |
| `orders/create`    | A new order is placed                                             | Ingests order data for purchase attribution and revenue tracking |
| `orders/updated`   | An existing order is modified (fulfillment, refund, cancellation) | Updates attributed revenue and order status                      |
| `orders/cancelled` | An order is cancelled                                             | Marks the conversion as cancelled and adjusts revenue            |
| `customers/create` | A new customer account is created                                 | Adds the customer to the identity graph                          |
| `customers/update` | Customer profile changes (email, address, tags)                   | Merges updated data into the existing identity profile           |
| `products/create`  | A new product is published                                        | Updates the product catalog for content ID matching              |
| `products/update`  | A product is modified (price, title, variants)                    | Syncs product changes for accurate event parameters              |
| `app/uninstalled`  | The Upstack app is removed from the store                         | Deactivates the source and stops data collection                 |

<Info>
  Upstack does not register webhooks for draft orders, inventory, or fulfillment events. These may be added in future releases based on customer demand.
</Info>

## How Webhook Processing Works

When Shopify fires a webhook, the following pipeline executes:

1. **Receive** — Upstack's ingestion endpoint receives the webhook payload and validates the HMAC signature to confirm it originated from Shopify.
2. **Normalize** — The raw Shopify payload is transformed into Upstack's internal event schema. For example, an `orders/create` webhook becomes a `Purchase` event with standardized fields.
3. **Enrich** — The event is passed through identity resolution. If the order includes a customer email, Upstack links it to any existing anonymous sessions from that visitor.
4. **Store and forward** — The normalized event is stored for analytics and simultaneously queued for delivery to any active destinations.

<Warning>
  **HMAC validation is mandatory.** Every incoming webhook is verified against your store's shared secret. If validation fails, the payload is rejected and logged as a security event. You do not need to configure this — it's handled automatically during app installation.
</Warning>

## Retry and Reliability

Shopify's webhook infrastructure includes automatic retry logic:

* If Upstack's endpoint returns a non-2xx response, Shopify retries the webhook up to **19 times** over a 48-hour period with exponential backoff.
* If all retries fail, Shopify marks the webhook as failed. Upstack's daily reconciliation sync catches these gaps by pulling any missing orders via the Shopify API.
* Webhooks that consistently fail may cause Shopify to automatically remove the webhook registration. If this happens, Upstack detects the removal and re-registers the webhook.

This dual approach (webhooks + daily reconciliation) ensures no data is permanently lost, even during extended outages or high-traffic events like flash sales.

## Verifying Webhooks Are Working

<Steps>
  <Step title="Check webhook status in the Upstack dashboard">
    Navigate to **Integrations → Sources → Shopify**. The source detail page shows a **Webhook Health** indicator:

    * **Healthy** (green) — webhooks are being received and processed normally
    * **Delayed** (yellow) — some webhooks have failed but retries are in progress
    * **Failing** (red) — webhooks are consistently failing; check Shopify admin for details
  </Step>

  <Step title="Trigger a test event">
    Place a test order on your Shopify store (you can use Shopify's **Bogus Gateway** for free test transactions). Within 30 seconds, the order should appear in the Upstack **Live Event Stream** as a `Purchase` event.
  </Step>

  <Step title="Check Shopify's webhook logs">
    In your Shopify admin, go to **Settings → Notifications → Webhooks**. Shopify shows recent webhook deliveries with status codes. Look for deliveries to Upstack's endpoint — they should all show `200` responses.

    <Info>
      Shopify's webhook log in the admin panel shows the last 30 days of delivery attempts. Use this to diagnose intermittent failures.
    </Info>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Webhooks show as 'failing' in Shopify admin">
    If Shopify reports webhook delivery failures to Upstack's endpoint:

    1. Check the [Upstack status page](https://status.upstackdata.com) for any ongoing incidents
    2. Verify your Shopify store hasn't recently changed its domain (this can invalidate webhook registrations)
    3. In the Upstack dashboard, go to **Integrations → Sources → Shopify** and click **Reconnect** to re-register webhooks

    Failed webhooks are retried by Shopify for up to 48 hours, and Upstack's daily reconciliation sync fills any remaining gaps.
  </Accordion>

  <Accordion title="Order data is delayed but eventually arrives">
    Brief delays (under 5 minutes) are normal during high-traffic periods. Shopify queues webhooks and delivers them in order, which can introduce latency during peak times like Black Friday.

    If delays consistently exceed 30 minutes, check whether your Shopify store is near its API rate limit. High-volume stores on the Basic plan may experience more webhook queuing than stores on Advanced or Plus plans.
  </Accordion>

  <Accordion title="Webhooks were removed by Shopify">
    Shopify automatically removes webhook registrations if the receiving endpoint returns errors for an extended period. Upstack monitors for this and re-registers webhooks automatically.

    If you notice a gap in data, check **Integrations → Sources → Shopify** for a "Webhooks re-registered" notification. Any missed data during the gap is recovered during the next daily reconciliation sync.
  </Accordion>
</AccordionGroup>

***

**Still stuck?** Contact [support@upstackdata.com](mailto:support@upstackdata.com) with your Pixel ID and a description of the issue. We typically respond within a few hours.

## Related

<CardGroup cols={2}>
  <Card title="Connect Shopify" icon="shopify" href="/sources/shopify">
    Step-by-step setup guide for connecting your Shopify store.
  </Card>

  <Card title="Troubleshooting: Data Stopped Syncing" icon="wrench" href="/troubleshooting/data-stopped-syncing">
    End-to-end diagnostic guide when source data stops flowing into Upstack.
  </Card>

  <Card title="Events Taxonomy" icon="bolt" href="/data-dictionary/event-taxonomy">
    How Shopify webhook events map to Upstack's standard event taxonomy.
  </Card>
</CardGroup>