saleor-webhooks

Saleor Webhooks

Before writing code

Fetch live docs:

1. Fetch https://docs.saleor.io/docs/developer/extending/webhooks/overview for webhook overview
2. Web-search site:docs.saleor.io async sync webhook events list for event type reference
3. Web-search site:docs.saleor.io webhook subscription payload for subscription query syntax
4. Web-search site:docs.saleor.io webhook payload signature JWS verification for signature verification
5. Web-search site:docs.saleor.io webhook retry policy for retry behavior

Async vs Sync Webhooks

Aspect	Async Webhooks	Sync Webhooks
Timing	Fired after the action completes	Fired during the action, blocks response
Response	Saleor ignores the response body	Saleor uses the response to alter behavior
Timeout	Longer (configurable)	Short (seconds) -- must respond quickly
Retry	Retried on failure	Not retried -- failure may abort the operation
Use Case	Notifications, syncing, analytics	Tax calculation, payment gateways, shipping rates

Key Async Event Types

Event	Trigger
ORDER_CREATED	New order is placed
ORDER_UPDATED	Order fields are modified
ORDER_CONFIRMED	Order is confirmed
ORDER_FULFILLED	All items in the order are fulfilled
ORDER_CANCELLED	Order is cancelled
ORDER_FULLY_PAID	Order payment is complete
PRODUCT_CREATED	New product is created
PRODUCT_UPDATED	Product fields are modified
PRODUCT_DELETED	Product is deleted
CUSTOMER_CREATED	New customer account is created
CUSTOMER_UPDATED	Customer data is modified
CHECKOUT_CREATED	New checkout session starts
CHECKOUT_UPDATED	Checkout data changes
FULFILLMENT_CREATED	Fulfillment record is created
INVOICE_SENT	Invoice email is dispatched

Key Sync Event Types

Event	Expected Response
PAYMENT_GATEWAY_INITIALIZE_SESSION	Payment session configuration
TRANSACTION_INITIALIZE_SESSION	Transaction processing data
TRANSACTION_PROCESS_SESSION	Transaction result
TRANSACTION_CHARGE_REQUESTED	Charge confirmation
TRANSACTION_REFUND_REQUESTED	Refund confirmation
SHIPPING_LIST_METHODS_FOR_CHECKOUT	Available shipping methods and rates
CHECKOUT_CALCULATE_TAXES	Tax amounts for checkout lines
ORDER_CALCULATE_TAXES	Tax amounts for order lines
CHECKOUT_FILTER_SHIPPING_METHODS	Filter available shipping options
ORDER_FILTER_SHIPPING_METHODS	Filter shipping for existing orders

Sync webhooks must return a response in the expected format -- fetch live docs for each event's response schema.

Subscription Payloads

Saleor uses GraphQL subscription queries to define webhook payload shapes:

subscription OrderCreated {
  event {
    ... on OrderCreated {
      order { id number total { gross { amount currency } } user { email } }
    }
  }
}

This subscription query is attached to the webhook configuration and controls exactly which fields appear in the delivered payload.

Subscription Payload Benefits

Benefit	Detail
Precise data	Request only the fields you need
Reduced payload size	No unnecessary nested objects
Type safety	Payload matches the subscription query shape
Versioning	Update the query when you need new fields

Webhook Registration

Via App Manifest

Webhooks are declared in the App manifest and registered automatically during installation:

Manifest Field	Purpose
webhooks[].name	Human-readable webhook name
webhooks[].asyncEvents	List of async event types
webhooks[].syncEvents	List of sync event types
webhooks[].query	GraphQL subscription query for payload
webhooks[].targetUrl	URL to receive the webhook POST
webhooks[].isActive	Enable or disable the webhook

Via GraphQL API

Mutation	Purpose
webhookCreate	Register a new webhook
webhookUpdate	Modify an existing webhook
webhookDelete	Remove a webhook

Staff users or Apps with MANAGE_APPS permission can manage webhooks via the API.

Payload Signature Verification

Saleor signs every webhook payload to ensure authenticity. Since Saleor 3.5+, the default method is JWS (JSON Web Signature) with RS256. Legacy HMAC-SHA256 is deprecated.

Header	Value
Saleor-Signature	JWS signature (default) or HMAC-SHA256 hex digest (deprecated)
Saleor-Event	The event type (e.g., order_created)
Saleor-Domain	The Saleor instance domain
Saleor-Api-Url	Full URL of the Saleor GraphQL endpoint

Signature Methods

Method	Status	How It Works
JWS (RS256)	Default (3.5+)	Payload-detached JWS; verify with public key from /.well-known/jwks.json
HMAC-SHA256	Deprecated	Only used when a webhook secret key is explicitly set; will be removed in 4.0

JWS Verification Steps

Step	Action
1	Read the Saleor-Signature header (JWS compact serialization)
2	Fetch the public key from <saleor-domain>/.well-known/jwks.json
3	Verify the JWS signature using the RS256 public key
4	Reject the request if verification fails

The saleor-app-sdk provides built-in middleware for automatic signature verification. Always verify signatures before processing any webhook payload.

Retry Policy

Aspect	Detail
Async retries	Saleor retries failed async webhooks with exponential backoff
Max attempts	Configurable -- fetch live docs for default
Failure criteria	Non-2xx HTTP response or connection timeout
Sync retries	Sync webhooks are not retried
Circuit breaker	Saleor may disable a webhook after repeated failures

Webhook Handler Pattern

Step	Action
1	Receive POST request at targetUrl
2	Verify payload signature (JWS or HMAC)
3	Parse the JSON payload
4	Route by event type (Saleor-Event header)
5	Process the event (sync: return response; async: acknowledge with 200)
6	Return appropriate HTTP status

For async webhooks, return HTTP 200 immediately and process the event asynchronously if it requires heavy work.

Error Handling

Scenario	Behavior
App returns 5xx	Async: retried; Sync: operation may fail
App returns 4xx	Async: retried; Sync: operation may fail
App timeout	Async: retried; Sync: fallback or failure
Invalid signature	App should return 401 and not process
Malformed payload	App should return 400 and log the error

Best Practices

• Always verify payload signatures (JWS or HMAC) before processing any webhook
• Use subscription queries to minimize payload size and improve performance
• Return HTTP 200 immediately for async webhooks, then process asynchronously
• Keep sync webhook handlers fast -- they block the user-facing operation
• Monitor webhook delivery status in the Saleor Dashboard
• Implement idempotency for async handlers -- the same event may be delivered more than once
• Use the Saleor-Event header to route to the correct handler function
• Log failed webhook deliveries for debugging and alerting

Fetch the Saleor webhook documentation for exact event type enumerations, subscription query patterns, and retry configuration before implementing.