用途:让后端与每个商家使用应用的关系保持同步,覆盖安装、试用、订阅到卸载的完整生命周期。处理的事件包括 app.installed、app.store.authorize、app.updated、app.uninstalled、app.trial.、app.subscription.、app.settings.updated 与 app.feedback.created。这些属于 app.* 事件,默认自动投递到已配置的 webhook_url,无需调用订阅接口;非应用事件(order.、product.)才需要 salla-webhooks 中的订阅动作。
主要能力与用法:用 Salla Partners MCP 执行 salla_apps action=connect 设置 webhook_url(webhook_security_strategy 为 signature),用 action=get 查看应用状态与 webhook_secret。签名密钥需在 Partner Portal 创建或轮换并存入密钥管理服务。事件到达时先验签,快速返回 200,再异步处理;按 merchant 做 upsert 保持幂等。安装流程需在 app.installed 中创建商家记录与默认值,在 app.store.authorize 中保存或更新 access_token、refresh_token 与过期时间。app.updated 仅作信号,新令牌由随后的 app.store.authorize 持久化。卸载时 enqueue 清理任务,撤销令牌并按保留/GDPR 策略删除或匿名化 PII。试用与订阅事件用于开放或限制功能,app.subscription.* 需按 data.item_type(plan 或 addon)分支,并留意 data.store_type 区分测试与正式店铺。还给出了商家状态机:installed→trial→active/restricted→uninstalled。
适用场景与限制:适合需要构建或维护 Salla 应用后端、编写 webhook 处理器的开发者。事件到达顺序不保证,created_at 仅秒级精度,不能单独作为幂等键,需使用 subscription_id 或请求体哈希。异步任务失败 Salla 不可见,需死信队列、退避重试与告警。具体超时与重试策略由 salla-webhooks 负责,订阅与计划状态的完整逻辑见 salla-app-billing。官方事件负载文档见 https://docs.salla.dev/421413m0.md。