Saleor App
Guide for building apps that extend Saleor via webhooks and the GraphQL API. Framework-agnostic protocol documentation with Next.js examples using @saleor/app-sdk.
When to Apply
- Defining an app manifest or registering webhooks
- Handling async/sync webhook events from Saleor
- Authenticating requests (registration handshake, JWT, signature verification)
- Storing app settings in Saleor metadata
- Building Dashboard UI inside the iframe
- Making GraphQL calls with app tokens
- Debugging webhook failures, auth errors, or permission issues
- Deciding who can view the app and what they should see (user vs app scope)
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Protocol | CRITICAL | protocol- |
| 2 | Permissions | CRITICAL | permissions- |
| 3 | Webhooks | HIGH | webhook- |
| 4 | Data & Settings | HIGH | data- |
| 5 | Dashboard UI | MEDIUM | dashboard- |
| 6 | Development | MEDIUM | dev- |
Quick Reference
1. Protocol (CRITICAL)
protocol-manifest— App manifest, required endpoints, permissions, extensionsprotocol-auth— Registration handshake, APL, token scopes, JWT/signature verification
2. Permissions (CRITICAL)
permissions-access-scopes— User scope vs app scope, client-side permission checks, JWT middleware patterns
3. Webhooks (HIGH)
webhook-async— Async event handling, payload typing, retry policy, signature verificationwebhook-sync— Sync event handling, response schemas, performance constraintswebhook-external— Receiving webhooks from external services, multi-tenant routing
4. Data & Settings (HIGH)
data-graphql— GraphQL from apps: client setup, auth headers, codegen, app vs user tokensdata-settings— MetadataManager, EncryptedMetadataManager, domain-scoped persistence
5. Dashboard UI (MEDIUM)
dashboard-appbridge— AppBridge iframe protocol, actions, events, theme/locale sync
6. Development (MEDIUM)
dev-debug— Common errors, webhook dry runs, tunnel setup, debugging checklist