Best Practice for Shopify Webhooks: Rest API | Topics List

Shopify Webhooks enable real-time communication between Shopify and external applications. They provide a way for developers to receive notifications about events that occur in a Shopify store, such as new orders or inventory updates. By configuring webhooks, developers can streamline processes and build integrations that enhance the functionality and automation of their Shopify stores.


Shopify Webhooks Overview

shopify webhooks

Webhooks serve as a mechanism for apps to synchronize with Shopify data or trigger actions in response to specific events within a shop. They offer a more efficient approach compared to constantly polling for changes in shop data. For instance, a webhook can notify your app whenever a user modifies a product in the Shopify admin, allowing your app to promptly respond and perform the necessary actions corresponding to the product change.

Webhook data is categorized based on topics. To access the comprehensive list of supported webhook topics, please consult the reference documentation of the GraphQL Admin API or the REST Admin API.


Use cases

Common Webhook use cases include:

Sending alerts and notifications to instant messaging (IM) clients and pagers.
Gathering data for data warehousing purposes.
Integrating with accounting software systems.
Filtering order items and notifying shipping companies about orders.
Deleting customer data from a database when an app is uninstalled.


Shopify Webhook concepts

To provide a better understanding of the content in this guide, the following definitions clarify webhook concepts:

1. Webhook: It represents a single event message sent by Shopify. When triggered, Shopify sends a webhook to the designated endpoint specified in the app’s webhook subscription. The webhook includes a JSON payload in the body and relevant metadata in the headers.

2. Webhook topic: It refers to a category or class of webhook events. Each topic determines when webhook events are generated and the contents of the webhook payload. For instance, the “orders/create” topic triggers webhook events whenever a new order is created in a shop, and the payload includes the details of the newly created order.

3. Webhook subscription: It is a persistent data object created by an app using the REST Admin API or GraphQL Admin API. A webhook subscription defines various aspects, such as the webhook endpoint, the specific webhook topics to subscribe to, and any additional configuration settings required for handling the webhook events.


Shopify Webhook behavior

Here is how webhooks act in Shopify:

Webhook order

Webhooks are dispatched sequentially for each combination of resource and topic. This means that, for instance, every “products/update” webhook related to the same product will be delivered in the order they were triggered.

API versions

The X-Shopify-API-Version header indicates the version of the Admin API employed to serialize the webhook event payload. You have the ability to configure your app to utilize a specific API version for all webhooks, and that version will be employed whenever feasible.

In the event that an app is configured to use an unsupported API version, Shopify will automatically revert to the oldest supported version as a fallback.


Limitations

  • The ordering of webhook events between different topics for the same resource is not guaranteed. For instance, a “products/update” webhook may be delivered before a “products/create” webhook for the same product.
  • The webhooks API follows an “at least once” delivery approach for webhook events. This means that an endpoint might receive the same webhook event multiple times. To identify duplicate events, you can compare the X-Shopify-Webhook-Id header with previous events.
  • It’s important to note that webhook delivery is not always guaranteed. Therefore, it is recommended to implement reconciliation jobs or processes to periodically fetch data from Shopify, ensuring data consistency and integrity.

Testing Shopify webhooks

Testing Shopify webhooks

To verify your webhook configuration or examine the webhook payload, you have the option to trigger the webhook using the following methods:

  • Manual triggering: Use the Shopify CLI webhook trigger command to manually initiate the webhook. It’s important to note that manually triggering webhooks does not test your webhook subscriptions. It simply allows you to initiate a specific webhook event for testing purposes.
  • Action-based triggering: Perform the associated action in a Shopify store where your app is installed. By carrying out the relevant action, such as creating an order or updating a product, you can trigger the corresponding webhook and observe the resulting payload.

Both methods enable you to test and inspect the behavior of your webhooks in different scenarios.


Shopify Webhooks Troubleshooting

If a webhook encounters 13 or more consecutive delivery failures, Shopify will send you an email notification. Additionally, if a webhook experiences 19 consecutive failed retry attempts, it will be automatically removed.

For apps created in the Partner Dashboard or using Shopify CLI, you can utilize the webhook delivery metrics report. This report provides valuable insights into delivery failures, allowing you to troubleshoot issues and gather performance-related information to improve webhook reliability.


Shopify webhooks: Some more basics

Retrieves a Shopify webhooks list

webhook in Shopify

Parameters


api_version
string
required

address

Fetch webhook subscriptions for a specific URI that receives POST requests.


created_at_max

Retrieve webhook subscriptions that were created before a specified date and time (in the format: 2014-04-25T16:15:47-04:00).


created_at_min

Retrieve webhook subscriptions that were created after a specified date and time (in the format: 2014-04-25T16:15:47-04:00).


fields

Use the “properties” parameter to specify a comma-separated list of the desired properties for each item in the resulting list. This allows you to narrow down the returned items to only include the specified properties.


limit
≤ 250
default 50

To ensure successful retrieval of webhook subscriptions, make sure to set the “maximum” parameter within the allowed range. Setting this parameter beyond the maximum limit will result in an error.


since_id

To limit the returned list to webhook subscriptions with an ID greater than the specified “since_id,” use this parameter to filter the results accordingly. Only webhook subscriptions with IDs greater than the provided “since_id” will be included in the returned list.


topic
Show webhook subscriptions with a given topic. For valid values, refer to the list of event topics.

updated_at_max

Display webhook subscriptions that are associated with a specific topic. Please refer to the list of valid event topics for accurate values.


updated_at_min

Retrieve webhooks that were modified before a specified date and time (format: 2014-04-25T16:15:47-04:00).


Leave a Comment