Modify your payloads

Shopify provides you with a way to modify the payload you receive when you subscribe to webhook topics. Unlike filters, which always return the same payload, this feature enables you to specify what subset of information is most relevant to your use case from a webhook.

This can be especially useful in instances where you may be most interested in only a subset of fields from very large payloads, like the orders/updated webhook topic.

Anchor to How to modify a webhook payloadHow to modify a webhook payload

There are two recommended ways to implement payload modifications. Both require you to update your webhook subscription's configuration:

Using your app configuration file: As a list in the include_fields argument via your app configuration file.

Using GraphQL Admin API: As a list in the includeFields input field in the webhookSubscription argument when subscribing with the GraphQL Admin API.

You denote nested fields by using a period:

When include_fields are provided, only the specified fields will be included in the webhook payload. If no include_fields are provided, all fields will be included in the webhook payload.

Anchor to Debouncing, and why it may occur when you modify payloadsDebouncing, and why it may occur when you modify payloads

When you modify a payload to only include a subset of fields, you may run into debouncing. Debouncing is the process by which a webhook delivery system attempts to reduce duplicate webhooks. Shopify defines "duplicate webhooks" as webhooks with identical payloads.

Debouncing is used to avoid unnecessary executions and minimize the likelihood of bursty webhook traffic. Debouncing only occurs when webhooks are sent within a small time window.

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

Anchor to Example: Orders updatesExample: Orders updates

Suppose your app needs to know when an update has occurred to an order. You may choose to only include fields id (this is the order ID) and line_items.title in the payload.

Suppose an update to an order occurs, like a change in current total price from $4.00 to $4.50 immediately afterwards. Your app would receive a webhook with just the id and line_items.title in the payload.

Now suppose another order update happens, like the product's price is modified again, this time to $5.00. Shopify would debounce the second webhook because the id and line_items.title are the same and were going to be delivered within a small time window of each other.

However, if the event that occurred was a change to the title, the webhook would not be debounced because the payload would be different.