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.
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.
Asynchronous webhooks support the following protocols:
- Google Cloud Pub/Sub
- AWS SQS
A protocol is chosen based on the
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).
Webhook endpoints must respond within 20 seconds, including the network latency.
If your application performs long-running operations, consider using a task queue instead.
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)
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:
To use the Google Cloud Pub/Sub properly, you need to set the
GOOGLE_APPLICATION_CREDENTIALS environment variable.
All webhooks with the
awssqs scheme will be treated as AWS SQS webhooks.
The structure of
targetUrl should be as below:
FIFO queues (ending in
.fifo) must be configured to have
MessageGroupID will be set to current
Site's domain name.
Available webhook events
The WebhookEventTypeAsyncEnum represents the latest list of asynchronous webhooks