Skip to main content

Asynchronous Events

Architecture​

Asynchronous webhooks can be used for reacting to the events emitted by Saleor.

The worker instance will send the event payload via the chosen protocol. Your App or service should acknowledge receiving the payload, by responding with HTTP 200 status. If a successful response has not been received, for example in the case of temporary service unavailability, the worker instance will retry delivery. The delivery is triggered a maximum of five times. Behind the scenes, Saleor uses an exponential backoff strategy with the retry interval calculated as 10 * (2**retries) seconds.

The asynchronous events are meant to be used for Apps or services that do not require processing on the Saleor side. If you need to send data back to the user (for example, calculated shipping cost), you should use a synchronous webhook.

Examples of the use cases​

  • Sending an order confirmation to the company chat.
  • Synchronizing stocks with an external warehousing system.
  • Updating Elasticsearch or Algolia indexes after changing product descriptions.
  • Triggering frontend SSR for new pages.

Permissions​

Managing webhooks is available for users with the MANAGE_APPS permission. The App can also create and modify its own webhooks without the need for additional permissions.

Webhook protocols​

Asynchronous webhooks support the following protocols:

  • HTTP(S)
  • Google Cloud Pub/Sub
  • AWS SQS

A protocol is chosen based on the targetUrl scheme.

HTTP(S)​

Webhook payloads are sent in POST requests.

All webhooks with targetUrl, where the scheme is HTTP(S) will use this protocol.

While HTTPS webhooks are a familiar concept and may seem easy to implement, ensure your endpoint can handle the same level of concurrency that you expect from the monitored events. Saleor Cloud will do its best to deliver webhooks in real-time, which could mean more traffic than your servers can handle. Because of this and the possibility of losing events when the destination server is down, we recommend using a queue like Google Cloud Pub/Sub or AWS SQS (see below).

Time limits​

Webhook endpoints must respond within 20 seconds, including the network latency.

If your application performs long-running operations, consider using a task queue instead.

Fault tolerance​

Event delivery will be retried up to 5 times with exponential backoff if:

  • the endpoint cannot be reached
  • the endpoint does not respond in time
  • the endpoint responds with a transient HTTP error code (5xx)

Event delivery will not be reattempted if:

  • the endpoint responds with an HTTP redirect (3xx)
  • the endpoint responds with a non-transient HTTP error code (4xx)

Sending webhooks to Azure Service Bus​

You can use HTTP webhooks to deliver messages to Azure System Bus queues.

To do this, set the endpoint address to the HTTP endpoint of the Azure Service Bus queue or topic.

The structure of targetUrl should be as below:

https://<service-namespace>.servicebus.windows.net/<queue-or-topic>/messages

Then, add the following custom headers according to the Azure System Bus documentation:

  • Authorization
  • BrokerProperties

Note that Content-Type cannot be specified as a custom header and will be filled by Saleor when sending the webhook.

Google Cloud Pub/Sub​

All webhooks with the gcpubsub scheme will be treated as the Google Cloud Pub/Sub webhooks. The structure of the targetUrl scheme should be as below:

gcpubsub://cloud.google.com/projects/<your-project>/topics/<your-topic>

To use the Google Cloud Pub/Sub properly, you need to set the GOOGLE_APPLICATION_CREDENTIALS environment variable.

AWS SQS​

All webhooks with the awssqs scheme will be treated as AWS SQS webhooks.

The structure of targetUrl should be as below:

awssqs://<access-key-id>:<secret-access-key>@sqs.<region>.amazonaws.com/<account-id>/<queue-name>
note

FIFO queues (ending in .fifo) must be configured to have ContentBasedDeduplication enabled. MessageGroupID will be set to Saleor's domain name.

Available webhook events​

The WebhookEventTypeAsyncEnum represents the latest list of asynchronous webhooks