用途:为 Salla 应用搭建可靠的 Webhook 集成,覆盖建服务器、订阅事件、校验投递、快速响应与幂等处理。若事件已有 App Function 触发器,应优先使用它(运行在 Salla 沙箱、无需验签、自带鉴权),仅当没有对应触发器时才用 Webhook。
主要能力:通过 Salla Partners MCP 的 salla_apps action=connect 设置 webhook_url、安全策略与自定义头;salla_events action=list/subscribe 订阅店铺事件(app.* 事件默认自动投递,无需订阅)。店铺级 Webhook 也可用 Admin API(https://api.salla.dev/admin/v2),注册为 POST /webhooks/subscribe,需 webhooks.read_write 权限。
安全策略:token 为 Authorization 头与密钥的明文相等比较;signature 为对原始请求体的 HMAC-SHA256,需在任何 JSON 中间件解析前捕获原始字节,并用时间安全比较;none 表示不校验。新 Webhook 默认 version 2,必须显式设置策略,省略会被当作 none。密钥在 Partner Portal 创建/轮换,部署前用 salla_apps action=get 读取实时值。
条件规则:可在注册/更新体中传 rule(需 version 2),由 Salla 侧按事件负载过滤,支持 =、!=、>、< 及 AND/OR,字符串用反引号,且只能使用该事件类别支持的属性。
限制:@salla.sa/webhooks-actions 仅支持 Express,基于文件系统的动态 require 不适用于 Next.js 等无服务器运行时;订阅会整体替换列表,需每次包含全部事件,清空需 clear_all: true。已发布应用的策略变更需重新审批,期间线上店铺仍用已批准配置。