Skip to main content

createWebhookSubscription

Subscribes the calling token to a topic. The destination is registered with the delivery service and the subscription is stored right away, with consentState: Pending. Deliveries start once the destination has consented to the handshake the delivery service performs; until then nothing is sent. The response is the only place the signingSecret is ever returned.

Besides webhook_subscriptions:write, the token needs read access to the topic's subject type — the scope listed for the topic, e.g. orders:read for order/completely-shipped. Without it the mutation fails with FORBIDDEN.

Required scopes​

The token needs the webhook_subscriptions:write access scope.

createWebhookSubscription(
  input: CreateWebhookSubscriptionInput!
): WebhookSubscription!

Arguments​

createWebhookSubscription.input ● CreateWebhookSubscriptionInput! non-null input​

Type​

WebhookSubscription object​

A request to be notified about a topic at a destination. Notifications carry only the ids of the affected entities and a timestamp; fetch the current state through the API. Subscriptions belong to the API token that created them: a token only sees and manages its own.

Delivery itself runs outside the shop, which is why every field from active through lastErrorMessage is a mirror of what the delivery service reports and is refreshed whenever the shop talks to it. A quiet shop's mirror can be up to a minute behind. Deliveries only start once the destination has consented, so a freshly created subscription reads consentState: Pending until then.