Subscription Webhook Payloads

note

Subscription Webhook Payloads for asynchronous events are available in Saleor 3.2.

Subscription Webhook payloads for synchronous events are available in Saleor 3.6.

Custom payloads

You can define webhook payloads in Saleor with GraphQL subscriptions. Subscription queries allow you to subscribe to different events and determine what fields should be returned in the payload.

Building subscription query

To build a subscription query you can use any GraphQL interface (like GraphQL Playground). Just like with building a GraphQL query, you can use prompts and build the whole subscription from our API. Payload generation will use resolvers/permissions that are normally used in our API. Inside the query, you must define the event type for which the payload will be generated. The event type must be supported by our subscription mechanism (see the list of supported events).

warning

When defining subscription payload for synchronous webhooks some fields are blocked to prevent circular calls.

The example below is a subscription query that would enable listening to the PRODUCT_UPDATED event and requesting the products id and name in the webhook payload:

subscription {
  event {
    ... on ProductUpdated {
      product {
        id
        name
      }
    }
  }
}

Creating webhook with subscription query

To create a webhook that will have its payload generated using a subscription, you need to use the same mutation as with standard webhooks. The only difference is passing the query field as an input with a subscription query converted to a string. Webhook with the query field defined will be treated as a subscription webhook, and its payload will be generated from the subscription query.

Example asynchronous webhook create mutation for subscription payload:

mutation {
  webhookCreate(
    input: {
      app: "<app_id>"
      name: "test_product_updated_subscription"
      targetUrl: "<webhook_url>"
      asyncEvents: [PRODUCT_UPDATED]
      query: "subscription{event{...on ProductUpdated{product{id name}}}}"
    }
  ) {
    errors {
      field
      message
    }
    webhook {
      id
    }
  }
}

Expand ▼

Example asynchronous webhook payload:

{
  "product": {
    "id": "UHJvZHVjdDo3Ng==",
    "name": "Coconut Juice"
  }
}

Example synchronous webhook create mutation for subscription payload:

mutation {
  webhookCreate(
    input: {
      app: "<app_id>"
      name: "test_payment_capture_subscription"
      targetUrl: "<webhook_url>"
      syncEvents: [PAYMENT_CAPTURE]
      query: "subscription{event{...on PaymentCaptureEvent{payment{id created}}}}"
    }
  ) {
    errors {
      field
      message
    }
    webhook {
      id
    }
  }
}

Expand ▼

Example synchronous webhook payload:

{
  "payment": {
    "id": "UGF5bWVudDoyNDE=",
    "created": "2022-08-03T08:52:04.202449+00:00"
  }
}

Synchronous webhooks payload

Defining synchronous webhook payloads using subscriptions is also supported. Each event subscription type has access to its specific object fields.

caution

Keep in mind that some fields that use the synchronous event to be resolved are not allowed to be called in synchronous webhook payload subscriptions.

Blocked fields for subscription payloads

Synchronous events are not allowed to request fields that are resolved using other synchronous events, which would lead to circular calls of the webhook. Fields that are currently unallowed:

Object	Fields
Checkout	shippingMethods, availableShippingMethods, availablePaymentGateways
Order	shippingMethods, availableShippingMethods

Permissions

Since subscriptions use the Saleor API to define a webhook payload, the App that has the webhook subscribed needs all the permissions that are typically required when querying for specified data. Otherwise, the payload will not be resolved correctly.