Skip to main content
POST
Create Webhook Subscription

Create Webhook Subscription

Subscribes your app to one topic on the store the access token belongs to. Every event on that topic is then POSTed to your callback URL, signed with this subscription’s own secret.

Required scope

Subscribing needs the read scope of the resource the topic is about — the same rule Shopify uses. A write scope implies its read scope. Without the topic’s scope the request is rejected with 403. Apps built when this endpoint required write_shop for every topic are still allowed to subscribe with write_shop, but events are only delivered while the installation holds the topic’s scope — the response then carries a warnings entry saying so. The scope is checked again on every delivery, so revoking it stops the data.

Request

The body may also be wrapped in Shopify’s resource envelope ({ "webhook": { "topic": ..., "address": ... } }).

Body Parameters

string
required
A topic from the topic reference that is subscribable through the API. app/installed and the GDPR topics are not: declare them in your app manifest instead.
string
required
Where deliveries are POSTed. address (Shopify’s name) is accepted as an alias. Must be a public http/https URL in production; use HTTPS.
string
default:"json"
Only json is supported — webhook bodies are always JSON.

Response

object
string[]
Present when the subscription was accepted through the legacy write_shop rule but the installation lacks the topic’s scope.

Example Response

Errors

Errors use the standard { errors } body.

Notes

  • Deliveries to this subscription are signed with its own secret (see Webhook Verification). To rotate it, delete the subscription and create it again.
  • Subscriptions your app creates here are never changed by your manifest: installing, re-authorising or publishing a new app version only manages the subscriptions declared in the manifest’s webhooks[].
  • All of an app’s subscriptions on a store are removed when the merchant uninstalls the app (after the app/uninstalled delivery).