Webhook best practices

In rare circumstances, you might experience delays receiving webhooks. However, webhooks are always sent with the most recent data for the given resource. The payload of the delivered webhook should reflect the most recent attributes for the resource between the time of the webhook's trigger and the webhook's eventual delivery.

If receiving webhooks up to a day late might cause issues in your app, then we recommend comparing the timestamp of the webhook to the current date and time.

If your app goes offline for an extended period of time, you can recover your webhook by re-registering it and importing the missing data.

To re-register a webhook, consult the app's code that initially registered the webhook. You can add a check that fetches all the existing webhooks and registers only the ones that you need.

To import the missing data, you can fetch data from the outage period and feed it into your webhook processing code.

When you use the includeFields argument in GraphQL or the fields property in REST to specify which fields should be sent by a webhook, you must include a field that always has a unique value. For example, you can include the updated_at field in the includeFields argument.

Including a field that always has a unique value prevents the webhook from being dropped as a duplicate, such as in cases when only the id field is requested.

Although the webhooks API is designed to minimize duplicate webhook events, it's still possible to receive the same event more than once. Your app should handle webhook events using idempotent operations, where receiving the same webhook event a second time in a row doesn't result in different outcomes, unless the underlying data has changed.

You can detect duplicate webhook events by looking for identical X-Shopify-Webhook-Id headers, or by comparing the payload directly to the previous state. For example, you could use a callback function to check if the webhook (webhookId) has already been received by looking it up in the receievedWebhooks object. If it has been received, then the function can return early to avoid duplicate processing.

Your app shouldn't rely solely on receiving data from Shopify webhooks. Because webhook delivery isn't always guaranteed, you should implement reconciliation jobs to periodically fetch data from Shopify.

You could do this in the background, or offer reconciliation and syncing options to the merchant. For example the UI of your app could contain a button that triggers a manual reconciliation process by calling the relevant API endpoint, and fetching the requested data.

Most query endpoints support both the created_at_min and updated_at_min filter parameters. These filters can be used to build a job that fetches all resources that have been created or updated since the last time the job ran.

Tracking traffic from Shopify's platform can be overwhelming, especially as you grow your app.

If you need to manage large volumes of event notifications to build a scalable and reliable system, then you can configure subscriptions to send webhooks to Amazon EventBridge and Google Cloud Pub/Sub rather than through HTTPS.

• Learn about configuring webhooks for your app.