Creating Webhook

To subscribe to a webhook, we need to first create an App with proper permissions.

App creation

Webhooks are available in Saleor to both Local and External Apps. Local App is an entity tightly integrated into Saleor whereas External App is an externally hosted application that can communicate with Saleor API and integrate into Saleor Dashboard.

Saleor Local Apps are custom Webhooks & Token pairs that can be used to connect apps and access Saleor API. Defining webhooks through Saleor Local Apps allows Saleor API to send real-time notifications or data to another application or service. It enables communication between different systems by delivering event-based information from one system to another. Use Saleor's webhook functionality to receive notifications and trigger custom actions or integrations in response to specific events.

Webhook creation

Using Dashboard

To create a webhook visit Webhooks & Events page which is available through the Configuration page. This page lists Local apps in your Saleor instance. Apps assign Permissions to the Webhooks & Tokens. Choose an App from the list or create a new one. On the App page click Create Webhook button which opens the Create Webhook form.

Submitting the Create Webhook form triggers the webhookCreate mutation. For fields explanation please check Using GraphQL section.

Using GraphQL

Let's assume that we want to extend the order processing app. The App should receive notifications whenever new orders are created in Saleor. To do so, we'll create a new webhook using the webhookCreate mutation. The mutation takes the following input:

• name: the name of the webhook.
• targetUrl: the URL of a service that will receive webhooks requests.
• asyncEvents: a list of the asynchronous events to subscribe to.
• syncEvents: a list of the synchronous events to subscribe to.
• app: the ID of the App to which the webhook belongs. Can be ommited, if the request has the Authentication header with the App access token.
• isActive: whether to activate the webhook.
• secretKey DEPRECATED, optional, the secret key used to create a hash signature with each payload.
• query: subscription query used to define a webhook payload, check Subscription Webhook Payloads page for details.
• customHeaders: custom headers, which will be added to HTTP request. There is a limitation of 5 headers per webhook and 998 characters per header. Only "X-" and "Authorization" keys are allowed.

mutation {
  webhookCreate(
    input: {
      name: "New orders notification"
      targetUrl: "https://order-processing-service.example.com"
      asyncEvents: [ORDER_CREATED]
      app: "QXBwOjk="
      isActive: true
      query: "
        subscription {
          event {
            ... on OrderCreated {
              order {
                id
                created
              }
            }
          }
        }
      "
      customHeaders: "{\"X-Key\": \"Value\"}"
    }
  ) {
    webhook {
      id
    }
    webhookErrors {
      field
      code
    }
  }
}

Expand ▼

If there are no errors in the response, the webhook is successfully created. From now on, whenever a new order is placed, the payload with the order data specified by subscription query will be sent to your targetUrl.

Managing app webhooks

After installation, the App can create a webhook subscription. To manage its own webhooks, no additional permissions are needed. If requests contain the app token in the Authentication header, the app argument will be automatically populated with the corresponding App.

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. For details check Subscription Webhook Payloads page.

tip

If you change the webhook subscription, you may need to update the webhook in the Saleor API. You can read more about it in the How to update app webhooks guide.

Updating a webhook

To update a webhook (e.g. to deactivate it or change the permissions), use the webhookUpdate mutation. The mutation takes similar input fields as the webhookCreate mutation. The example below shows how to deactive a webhook:

mutation {
  webhookUpdate(id: "V2ViaG9vazox", input: { isActive: false }) {
    webhook {
      isActive
    }
    webhookErrors {
      field
      code
    }
  }
}

Removing a webhook

To fully remove a webhook, use the webhookDelete mutation:

mutation {
  webhookDelete(id: "V2ViaG9vazox") {
    webhookErrors {
      field
      code
    }
  }
}