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.
Example: Marketing consent information for updated customers
Anchor link to section titled "Example: Marketing consent information for updated customers"Suppose you are building an app that relies on email marketing consent information any time a customer's information is updated. For example, you need to ensure you use this information to update a database of consent information, in order to comply with local regulation.
To get this information, you subscribe your app to the customers/update webhook topic.
When a customer is updated, you would receive a webhook with the following payload:
However, because you want the payload of the webhooks you receive from Shopify to match the payloads of webhooks you receive from other platforms, you are only interested in email marketing consent information (like the email marketing state, the opt-in level, or when consent information was updated).
To do this, you modify your webhook subscription configuration to only include "id", "email_marketing_consent", and "updated_at" in the payload. Now, any time a customer is updated, the customers/update webhook your app receives would instead have the following payload:
How to modify a webhook payload
Anchor link to section titled "How 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:
View Output
Modified webhook payload
Mutation
Input Variables
View Output
Modified webhook payload
Debouncing, and why it may occur when you modify payloads
Anchor link to section titled "Debouncing, 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.
Example: Orders updates
Anchor link to section titled "Example: 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.
Avoid debounces
Anchor link to section titled "Avoid debounces"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. A good starting point is to always include the fields "id" and "updated_at".