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

Key Async Event Types

Key Sync Event Types

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

Webhook Registration

Via App Manifest

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

Via GraphQL API

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.

Signature Methods

JWS Verification Steps

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

Retry Policy

Webhook Handler Pattern

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

Error Handling

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.