Shopify webhooks enable apps to receive notifications about particular events in a shop. They are useful for keeping your app in sync with Shopify data or as a trigger to perform additional actions after events occur, providing a performant alternative to continuously polling for changes.
openapi: 3.1.0
info:
title: Shopify Webhooks API
description: >-
Shopify webhooks enable apps to receive real-time HTTP notifications when
events occur in a shop. Apps subscribe to webhook topics and Shopify
delivers POST requests with event payloads to the registered callback URL.
This specification documents the webhook subscription management endpoints
and the standard webhook event payload structures.
version: '2025-01'
contact:
name: Shopify
url: https://shopify.dev/docs/api/webhooks
email: [email protected]
license:
name: Shopify API Terms
url: https://www.shopify.com/legal/api-terms
x-date: '2026-03-04'
servers:
- url: https://{store}.myshopify.com/admin/api/2025-01
description: Shopify Admin REST API
variables:
store:
default: my-store
description: The Shopify store subdomain
security:
- AccessToken: []
tags:
- name: Webhook Subscriptions
description: Create and manage webhook subscriptions
paths:
/webhooks.json:
get:
operationId: listWebhookSubscriptions
summary: Shopify Retrieve a list of webhook subscriptions
description: >-
Retrieves a list of webhooks for the authenticated app. Filter by
topic, creation date, or other criteria.
tags:
- Webhook Subscriptions
parameters:
- name: topic
in: query
description: Filter by webhook topic (e.g. orders/create)
schema:
type: string
- name: address
in: query
description: Filter by callback address
schema:
type: string
- name: created_at_min
in: query
description: Show webhooks created after this date
schema:
type: string
format: date-time
- name: created_at_max
in: query
description: Show webhooks created before this date
schema:
type: string
format: date-time
- name: updated_at_min
in: query
description: Show webhooks updated after this date
schema:
type: string
format: date-time
- name: updated_at_max
in: query
description: Show webhooks updated before this date
schema:
type: string
format: date-time
- name: limit
in: query
description: Maximum number of results (max 250, default 50)
schema:
type: integer
default: 50
maximum: 250
- name: since_id
in: query
description: Return webhooks after the specified ID
schema:
type: integer
- name: fields
in: query
description: Comma-separated list of fields to include
schema:
type: string
responses:
'200':
description: A list of webhook subscriptions
content:
application/json:
schema:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
post:
operationId: createWebhookSubscription
summary: Shopify Create a webhook subscription
description: >-
Creates a new webhook subscription. When the specified event occurs
Shopify sends an HTTP POST to the provided callback address with the
event payload in JSON or XML format.
tags:
- Webhook Subscriptions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- webhook
properties:
webhook:
$ref: '#/components/schemas/WebhookSubscriptionInput'
responses:
'201':
description: The created webhook subscription
content:
application/json:
schema:
type: object
properties:
webhook:
$ref: '#/components/schemas/WebhookSubscription'
'422':
description: Validation error (invalid topic or address)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/webhooks/count.json:
get:
operationId: getWebhookSubscriptionCount
summary: Shopify Retrieve a count of webhook subscriptions
description: >-
Retrieves a count of webhook subscriptions for the authenticated app.
tags:
- Webhook Subscriptions
parameters:
- name: topic
in: query
description: Count webhooks for a specific topic
schema:
type: string
- name: address
in: query
description: Count webhooks for a specific address
schema:
type: string
responses:
'200':
description: The webhook count
content:
application/json:
schema:
type: object
properties:
count:
type: integer
/webhooks/{webhook_id}.json:
get:
operationId: getWebhookSubscription
summary: Shopify Retrieve a single webhook subscription
description: Retrieves a webhook subscription by its ID.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/WebhookId'
- name: fields
in: query
description: Comma-separated list of fields to include
schema:
type: string
responses:
'200':
description: The webhook subscription
content:
application/json:
schema:
type: object
properties:
webhook:
$ref: '#/components/schemas/WebhookSubscription'
'404':
description: Webhook not found
put:
operationId: updateWebhookSubscription
summary: Shopify Update a webhook subscription
description: >-
Updates an existing webhook subscription. The address and fields can
be modified but the topic cannot be changed.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/WebhookId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- webhook
properties:
webhook:
$ref: '#/components/schemas/WebhookSubscriptionInput'
responses:
'200':
description: The updated webhook subscription
content:
application/json:
schema:
type: object
properties:
webhook:
$ref: '#/components/schemas/WebhookSubscription'
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: deleteWebhookSubscription
summary: Shopify Delete a webhook subscription
description: Deletes a webhook subscription by its ID.
tags:
- Webhook Subscriptions
parameters:
- $ref: '#/components/parameters/WebhookId'
responses:
'200':
description: Webhook deleted successfully
'404':
description: Webhook not found
components:
securitySchemes:
AccessToken:
type: apiKey
name: X-Shopify-Access-Token
in: header
description: Access token obtained via OAuth
parameters:
WebhookId:
name: webhook_id
in: path
required: true
description: The ID of the webhook subscription
schema:
type: integer
schemas:
WebhookSubscription:
type: object
description: A webhook subscription
properties:
id:
type: integer
description: Unique numeric identifier
address:
type: string
format: uri
description: The callback URL where Shopify sends webhook payloads
topic:
type: string
description: >-
The event topic. Common topics include orders/create,
orders/updated, orders/cancelled, orders/fulfilled,
products/create, products/update, products/delete,
customers/create, customers/update, customers/delete,
carts/create, carts/update, checkouts/create,
checkouts/update, inventory_levels/update,
fulfillments/create, fulfillments/update,
app/uninstalled, and shop/update.
enum:
- orders/create
- orders/updated
- orders/cancelled
- orders/fulfilled
- orders/paid
- orders/partially_fulfilled
- orders/delete
- products/create
- products/update
- products/delete
- customers/create
- customers/update
- customers/delete
- customers/enable
- customers/disable
- carts/create
- carts/update
- checkouts/create
- checkouts/update
- checkouts/delete
- collections/create
- collections/update
- collections/delete
- inventory_items/create
- inventory_items/update
- inventory_items/delete
- inventory_levels/connect
- inventory_levels/update
- inventory_levels/disconnect
- fulfillments/create
- fulfillments/update
- fulfillment_events/create
- fulfillment_events/delete
- refunds/create
- shop/update
- app/uninstalled
- app/scopes_update
- themes/create
- themes/publish
- themes/update
- themes/delete
format:
type: string
description: The data format for the webhook payload
enum:
- json
- xml
fields:
type: array
description: Optional list of top-level fields to include
items:
type: string
metafield_namespaces:
type: array
description: Optional metafield namespaces to include
items:
type: string
api_version:
type: string
description: The API version for the webhook payload
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
admin_graphql_api_id:
type: string
WebhookSubscriptionInput:
type: object
description: Input for creating or updating a webhook subscription
properties:
topic:
type: string
description: The event topic to subscribe to
address:
type: string
format: uri
description: The callback URL
format:
type: string
description: Payload format
enum:
- json
- xml
fields:
type: array
description: Fields to include in the payload
items:
type: string
metafield_namespaces:
type: array
description: Metafield namespaces to include
items:
type: string
WebhookHeaders:
type: object
description: >-
Standard HTTP headers included with every webhook delivery.
Apps should verify the X-Shopify-Hmac-SHA256 header to
authenticate that the webhook was sent by Shopify.
properties:
X-Shopify-Topic:
type: string
description: The webhook topic
X-Shopify-Hmac-Sha256:
type: string
description: Base64-encoded HMAC-SHA256 hash for verification
X-Shopify-Shop-Domain:
type: string
description: The shop domain
X-Shopify-API-Version:
type: string
description: The API version of the payload
X-Shopify-Webhook-Id:
type: string
description: Unique ID for this webhook delivery
Error:
type: object
description: Error response
properties:
errors:
description: Error details
oneOf:
- type: string
- type: object
additionalProperties:
type: array
items:
type: string