The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

Webhook

You can use webhook subscriptions to receive notifications about particular events in a shop. After you've subscribed to a webhook topic, your app can execute code immediately after specific events occur in shops that have your app installed, instead of having to make API calls periodically to check their status.

For example, you can rely on webhooks to trigger an action in your app when a customer creates a cart, or when a merchant creates a new product in their Shopify admin. By using webhooks, you can make fewer API calls overall, which makes sure that your apps are more efficient and update quickly.

For more information on how webhooks work and how to test them, refer to Webhooks overview and Webhook testing.

Considerations

If you create a webhook subscription through the Shopify admin, then that subscription won't be returned in API calls. These webhook subscriptions are associated solely to the shop, so the API can't access them.

Webhook subscriptions are scoped only to the app that they're registered to. This means that when a webhook subscription is registered to an app, other apps can't view, modify, or delete it.

To learn how to verify webhooks, refer to Verify the webhook.

Mandatory webhooks

Apps must subscribe to certain webhooks topics. You create mandatory webhooks either via the Partner Dashboard or by updating the app configuration TOML

.
TopicEvent
customers/data_request Requests to view stored customer data
customers/redact Requests to delete customer data
shop/redact Requests to delete shop data
Was this section helpful?
Anchor to section titled 'The Webhook subscription object'

The Webhook subscription object

Properties
address
->endpoint
Destination URI to which the webhook subscription should send the POST request when an event occurs.
api_version
read-only
->apiVersion
The Admin API version that Shopify uses to serialize webhook events. This value is inherited from the app that created the webhook subscription.
created_at
read-only
->createdAt
Date and time when the webhook subscription was created. The API returns this value in ISO 8601 format.
fields
->includeFields
An optional array of top-level resource fields that should be serialized and sent in the POST request. If absent, all fields will be sent.
format
->format
Format in which the webhook subscription should send the data. Valid values are JSON and XML. Defaults to JSON.
id
read-only
->id
Unique numeric identifier for the webhook subscription.
metafield_namespaces
->metafieldNamespaces
Optional array of namespaces for any metafields that should be included with each webhook.
private_metafield_namespaces
deprecated
Optional array of namespaces for any private metafields that should be included with each webhook.
topic
->topic
Event that triggers the webhook. You can retrieve data in either JSON or XML.
See list of webhook events.
updated_at
read-only
->updatedAt
Date and time when the webhook subscription was updated. The API returns this value in ISO 8601 format.
Was this section helpful?
{}The Webhook subscription object
{
  "address": "https://apple.com/uninstall",
  "api_version": "2019-10",
  "created_at": "2012-09-28T11:50:07-04:00",
  "fields": [
    "id",
    "updated_at"
  ],
  "format": "json",
  "id": 901431826,
  "metafield_namespaces": [
    "google",
    "inventory"
  ],
  "private_metafield_namespaces": [
    "myapp"
  ],
  "topic": "app/uninstalled",
  "updated_at": "2012-09-28T11:50:07-04:00"
}
Anchor to section titled 'POST request, Create a new Webhook'

post
Create a new Webhook

webhookSubscriptionCreate

Create a new webhook subscription by specifying both an address and a topic.

Amazon EventBridge and Google Pub/Sub webhook subscriptions use this field differently.For more information, refer to the Amazon EventBridge and Google Cloud Pub/Sub pages.

Anchor to section titled 'Parameters of Create a new Webhook'

Parameters

api_version
string
required
Was this section helpful?
Anchor to section titled 'Examples of Create a new Webhook'

Examples

Request body
webhook
Webhook resource
Was this section helpful?
post
/admin/api/2024-07/webhooks.json
Copy
curl -d '{"webhook":{"address":"pubsub://projectName:topicName","topic":"customers/update","format":"json"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-07/webhooks.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "webhook": {
    "id": 7448140624,
    "address": "pubsub://projectName:topicName",
    "topic": "customers/update",
    "created_at": "2024-10-07T22:10:16-04:00",
    "updated_at": "2024-10-07T22:10:16-04:00",
    "format": "json",
    "fields": [],
    "metafield_namespaces": [],
    "api_version": "unstable",
    "private_metafield_namespaces": []
  }
}
Anchor to section titled 'GET request, Retrieves a list of webhooks'

get
Retrieves a list of webhooks

webhookSubscriptions
Retrieves a list of webhooks.
Anchor to section titled 'Parameters of Retrieves a list of webhooks'

Parameters

api_version
string
required
address
Retrieve webhook subscriptions that send the POST request to this URI.
created_at_max
Retrieve webhook subscriptions that were created before a given date and time (format: 2014-04-25T16:15:47-04:00).
created_at_min
Retrieve webhook subscriptions that were created after a given date and time (format: 2014-04-25T16:15:47-04:00).
fields
Comma-separated list of the properties you want returned for each item in the result list. Use this parameter to restrict the returned list of items to only those properties you specify.
limit
≤ 250
default 50
Maximum number of webhook subscriptions that should be returned. Setting this parameter outside the maximum range will return an error.
since_id
Restrict the returned list to webhook subscriptions whose id is greater than the specified since_id.
topic
Show webhook subscriptions with a given topic. For valid values, refer to the list of event topics.
updated_at_max
Retrieve webhooks that were updated after a given date and time (format: 2014-04-25T16:15:47-04:00).
updated_at_min
Retrieve webhooks that were updated before a given date and time (format: 2014-04-25T16:15:47-04:00).
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a list of webhooks'

Examples

Was this section helpful?
get
/admin/api/2024-07/webhooks.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/webhooks.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "webhooks": [
    {
      "id": 4759306,
      "address": "https://apple.com",
      "topic": "orders/create",
      "created_at": "2024-10-07T22:08:17-04:00",
      "updated_at": "2024-10-07T22:08:17-04:00",
      "format": "json",
      "fields": [],
      "metafield_namespaces": [],
      "api_version": "unstable",
      "private_metafield_namespaces": []
    },
    {
      "id": 892403750,
      "address": "https://example.org/fully_loaded_1",
      "topic": "orders/cancelled",
      "created_at": "2021-12-01T05:23:43-05:00",
      "updated_at": "2021-12-01T05:23:43-05:00",
      "format": "json",
      "fields": [],
      "metafield_namespaces": [],
      "api_version": "unstable",
      "private_metafield_namespaces": []
    },
    {
      "id": 901431826,
      "address": "https://apple.com/uninstall",
      "topic": "app/uninstalled",
      "created_at": "2024-10-07T22:08:17-04:00",
      "updated_at": "2024-10-07T22:08:17-04:00",
      "format": "json",
      "fields": [],
      "metafield_namespaces": [],
      "api_version": "unstable",
      "private_metafield_namespaces": []
    },
    {
      "id": 1014196360,
      "address": "https://example.org/app_uninstalled",
      "topic": "app/uninstalled",
      "created_at": "2024-10-07T22:08:17-04:00",
      "updated_at": "2024-10-07T22:08:17-04:00",
      "format": "json",
      "fields": [],
      "metafield_namespaces": [],
      "api_version": "unstable",
      "private_metafield_namespaces": []
    }
  ]
}
Anchor to section titled 'GET request, Receive a single Webhook'

get
Receive a single Webhook

webhookSubscription
Retrieves a single webhook subscription. The properties desired in the result can be specified.
Anchor to section titled 'Parameters of Receive a single Webhook'

Parameters

api_version
string
required
webhook_id
string
required
fields
Comma-separated list of the properties you want returned for each item in the result list. Use this parameter to restrict the returned list of items to only those properties you specify.
Was this section helpful?
Anchor to section titled 'Examples of Receive a single Webhook'

Examples

Path parameters
webhookid=4759306
string
required
Was this section helpful?
get
/admin/api/2024-07/webhooks/4759306.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/webhooks/4759306.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "webhook": {
    "id": 4759306,
    "address": "https://apple.com",
    "topic": "orders/create",
    "created_at": "2024-10-07T22:08:17-04:00",
    "updated_at": "2024-10-07T22:08:17-04:00",
    "format": "json",
    "fields": [],
    "metafield_namespaces": [],
    "api_version": "unstable",
    "private_metafield_namespaces": []
  }
}
Anchor to section titled 'GET request, Receive a count of all Webhooks'

get
Receive a count of all Webhooks

webhookSubscriptionsCount
Retrieves a count of existing webhook subscriptions. The results can be filtered by address or by topic.
Anchor to section titled 'Parameters of Receive a count of all Webhooks'

Parameters

api_version
string
required
address
Webhook subscriptions that send the POST request to this URI.
topic
The topic of the webhook subscriptions. For valid values, refer to the list of event topics.
Was this section helpful?
Anchor to section titled 'Examples of Receive a count of all Webhooks'

Examples

Query parameters
topic=orders/create
The topic of the webhook subscriptions. For valid values, refer to the list of event topics.
Was this section helpful?
get
/admin/api/2024-07/webhooks/count.json?topic=orders/create
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/webhooks/count.json?topic=orders%2Fcreate" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "count": 1
}
Anchor to section titled 'PUT request, Modify an existing Webhook'

put
Modify an existing Webhook

webhookSubscriptionUpdate
Update a webhook subscription's topic or address URIs
Anchor to section titled 'Parameters of Modify an existing Webhook'

Parameters

api_version
string
required
webhook_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Modify an existing Webhook'

Examples

Path parameters
webhookid=4759306
string
required
Request body
webhook
Webhook resource
Was this section helpful?
put
/admin/api/2024-07/webhooks/4759306.json
Copy
curl -d '{"webhook":{"id":4759306,"address":"https://somewhere-else.com/"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-07/webhooks/4759306.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 200 OK
{
  "webhook": {
    "id": 4759306,
    "address": "https://somewhere-else.com/",
    "topic": "orders/create",
    "created_at": "2024-10-07T22:08:17-04:00",
    "updated_at": "2024-10-07T22:09:26-04:00",
    "format": "json",
    "fields": [],
    "metafield_namespaces": [],
    "api_version": "unstable",
    "private_metafield_namespaces": []
  }
}
Anchor to section titled 'DELETE request, Remove an existing Webhook'

del
Remove an existing Webhook

webhookSubscriptionDelete
Delete a webhook subscription
Anchor to section titled 'Parameters of Remove an existing Webhook'

Parameters

api_version
string
required
webhook_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Remove an existing Webhook'

Examples

Path parameters
webhookid=4759306
string
required
Was this section helpful?
del
/admin/api/2024-07/webhooks/4759306.json
Copy
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2024-07/webhooks/4759306.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{}
Anchor to section titled 'List of Webhook event topics'

List of Webhook event topics

Tip

To configure your subscription using the GraphQL Admin API, refer to the full list of topic names.

Occurs whenever a shop has uninstalled the app.

Resource: Shop
{} app/uninstalled : Webhook payload 
{
  "id": 548380009,
  "name": "Super Toys",
  "email": "super@supertoys.com",
  "domain": null,
  "province": "Tennessee",
  "country": "US",
  "address1": "190 MacLaren Street",
  "zip": "37178",
  "city": "Houston",
  "source": null,
  "phone": "3213213210",
  "latitude": null,
  "longitude": null,
  "primary_locale": "en",
  "address2": null,
  "created_at": null,
  "updated_at": null,
  "country_code": "US",
  "country_name": "United States",
  "currency": "USD",
  "customer_email": "super@supertoys.com",
  "timezone": "(GMT-05:00) Eastern Time (US & Canada)",
  "iana_timezone": null,
  "shop_owner": "John Smith",
  "money_format": "${{amount}}",
  "money_with_currency_format": "${{amount}} USD",
  "weight_unit": "kg",
  "province_code": "TN",
  "taxes_included": null,
  "auto_configure_tax_inclusivity": null,
  "tax_shipping": null,
  "county_taxes": null,
  "plan_display_name": "Shopify Plus",
  "plan_name": "enterprise",
  "has_discounts": false,
  "has_gift_cards": true,
  "myshopify_domain": null,
  "google_apps_domain": null,
  "google_apps_login_enabled": null,
  "money_in_emails_format": "${{amount}}",
  "money_with_currency_in_emails_format": "${{amount}} USD",
  "eligible_for_payments": true,
  "requires_extra_payments_agreement": false,
  "password_enabled": null,
  "has_storefront": true,
  "finances": true,
  "primary_location_id": 655441491,
  "checkout_api_supported": true,
  "multi_location_enabled": true,
  "setup_required": false,
  "pre_launch_enabled": false,
  "enabled_presentment_currencies": [
    "USD"
  ],
  "marketing_sms_consent_enabled_at_checkout": false,
  "transactional_sms_disabled": false
}
Was this section helpful?