---
title: Modify your payloads
description: >-
  A guide for how to select which fields in a payload of a webhook they'd like
  to receive.
source_url:
  html: 'https://shopify.dev/docs/apps/build/webhooks/customize/modify-payloads'
  md: 'https://shopify.dev/docs/apps/build/webhooks/customize/modify-payloads.md'
---

ExpandOn this page

* [How to modify a webhook payload](https://shopify.dev/docs/apps/build/webhooks/customize/modify-payloads.md#how-to-modify-a-webhook-payload)
* [Debouncing, and why it may occur when you modify payloads](https://shopify.dev/docs/apps/build/webhooks/customize/modify-payloads.md#debouncing-and-why-it-may-occur-when-you-modify-payloads)

# 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.

***

## 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](https://shopify.dev/docs/apps/structure/configuration).

**Using GraphQL Admin API:** As a list in the `includeFields` input field in the `webhookSubscription` argument when subscribing with the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/2024-04/mutations/webhookSubscriptionCreate#argument-webhooksubscription).

You denote nested fields by using a period:

## Example nested field

```json
"variants.price"
```

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.

#### TOML

```toml
name = "Example App"
client_id = "a61950a2cbd5f32876b0b55587ec7a27"
application_url = "https://www.app.example.com/"
embedded = true
handle = "example-app"


[access_scopes]
scopes = "read_products"


[auth]
redirect_urls = [ "https://example.com/api/auth" ]


[webhooks]
api_version = "2025-04"


  [[webhooks.subscriptions]]
  topics = ["products/update"]
  uri = "https://example.com/webhooks"
  include_fields = ["id", "variants.price", "variants.id", "updated_at"]


[pos]
embedded = false
```

**Modified webhook payload**

## shopify.app.config-name.toml

```json
{
  "id": 8685245005973,
  "variants": [
    {
      "id": 18685245005974,
      "price": "4654.00"
    },
    {
      "id": 18685245005975,
      "price": "4654.00"
    }
  ],
  "updated_at": "2025-05-22T10:25:02-04:00"
}
```

#### GraphQL

**Mutation**

```graphql
mutation subscribeToWebhook($topic: WebhookSubscriptionTopic!, $webhookSubscription: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(topic: $topic, webhookSubscription: $webhookSubscription) {
    userErrors {
      field
      message
    }
    webhookSubscription {
      topic
      uri
    }
  }
}
```

**Input Variables**

```json
{
  "topic":"PRODUCTS_UPDATE",
  "webhookSubscription": {
    "uri":"https://example.com/webhooks",
    "includeFields":["id", "variants.price", "variants.id", "updated_at"]
  }
}
```

**Modified webhook payload**

```json
{
  "id": 8685245005973,
  "variants": [
    {
      "id": 18685245005974,
      "price": "4654.00"
    },
    {
      "id": 18685245005975,
      "price": "4654.00"
    }
  ],
  "updated_at": "2025-05-22T10:25:02-04:00"
}
```

***

## 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.

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.

### 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.

***

* [How to modify a webhook payload](https://shopify.dev/docs/apps/build/webhooks/customize/modify-payloads.md#how-to-modify-a-webhook-payload)
* [Debouncing, and why it may occur when you modify payloads](https://shopify.dev/docs/apps/build/webhooks/customize/modify-payloads.md#debouncing-and-why-it-may-occur-when-you-modify-payloads)