Webhook
ShopFaaS Webhook 事件推送机制，供应用扩展接收店铺事件。
应用扩展通过 Webhook 接收店铺事件推送，实现订单通知、库存同步、客户管理等自动化场景。
事件类型
ShopFaaS 支持以下 Webhook 事件类型：
订单事件
| 事件 | 触发时机 | payload |
|---|---|---|
order.created | 订单创建 | { order_id, shop_id, customer_id, total, currency } |
order.paid | 订单支付成功 | { order_id, payment_id, amount, gateway } |
order.fulfilled | 订单履约完成 | { order_id, fulfillment_id, tracking_number } |
order.cancelled | 订单取消 | { order_id, reason } |
order.refunded | 订单退款 | { order_id, refund_id, amount, reason } |
商品事件
| 事件 | 触发时机 | payload |
|---|---|---|
product.created | 商品创建 | { product_id, shop_id, title, handle } |
product.updated | 商品更新 | { product_id, changes: string[] } |
product.deleted | 商品删除 | { product_id } |
product.inventory.updated | 库存变化 | { product_id, variant_id, old_quantity, new_quantity } |
客户事件
| 事件 | 触发时机 | payload |
|---|---|---|
customer.created | 客户创建 | { customer_id, shop_id, email } |
customer.updated | 客户信息更新 | { customer_id, changes: string[] } |
customer.deleted | 客户删除 | { customer_id } |
应用事件
| 事件 | 触发时机 | payload |
|---|---|---|
app.installed | 应用安装 | { app_id, shop_id, version } |
app.uninstalled | 应用卸载 | { app_id, shop_id } |
app.updated | 应用更新 | { app_id, old_version, new_version } |
Webhook 注册
应用在 plugin.json 中声明订阅的事件：
{
"name": "order-notify",
"version": "1.0.0",
"permissions": ["order:view"],
"webhooks": [
{
"event": "order.created",
"handler": "webhooks/order-created.ts"
},
{
"event": "order.paid",
"handler": "webhooks/order-paid.ts"
}
]
}Webhook 处理器
// plugins/order-notify/webhooks/order-created.ts
import type { WebhookHandler } from "@shopfaas/plugin-runtime";
const handler: WebhookHandler<"order.created"> = async (event, ctx) => {
const { order_id, total, currency } = event.payload;
// 调用原子 API 获取订单详情
const order = await ctx.api.orders.get(order_id);
// 发送通知（如调用第三方 API）
await fetch("https://your-notification-service.com/notify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
event: "order.created",
order,
}),
});
};
export default handler;Webhook 投递机制
HMAC 签名
每个 Webhook 有独立 secret，请求体 HMAC-SHA256 签名：
POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-ShopFaaS-Event: order.created
X-ShopFaaS-Signature: sha256=<hmac-signature>
X-ShopFaaS-Delivery: <delivery-uuid>
{
"event": "order.created",
"payload": { ... },
"timestamp": "2026-07-14T10:00:00Z",
"delivery_id": "uuid-1"
}验证签名
import crypto from "node:crypto";
function verifySignature(payload: string, signature: string, secret: string): boolean {
const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(`sha256=${expected}`));
}重试机制
Webhook 投递失败自动重试（指数退避）：
| 重试次数 | 间隔 |
|---|---|
| 1 | 1 分钟 |
| 2 | 5 分钟 |
| 3 | 30 分钟 |
| 4 | 2 小时 |
| 5 | 6 小时 |
| 6 | 24 小时 |
超过 6 次重试后标记为失败，可在后台手动重发。
响应要求
Webhook 接收端必须：
- 在 30 秒内返回 2xx 状态码（视为成功）
- 返回非 2xx 状态码视为失败，触发重试
- 接收端必须幂等（同一
delivery_id可能投递多次）
Webhook 管理
查看已注册 Webhook
店长在「设置 → 应用」查看已安装应用的 Webhook 列表。
查看投递历史
每个 Webhook 的投递历史（含 payload、响应状态、重试次数）可在后台查看。
手动重发
失败的 Webhook 投递可在后台手动重发。
应用扩展权限
应用在 plugin.json 中声明所需权限：
{
"permissions": ["order:view", "product:view"]
}权限码与 店铺角色权限码 一致。安装时店长可审查权限范围。
隔离机制
应用扩展采用强隔离：
| 层 | 隔离机制 |
|---|---|
| 运行时 | 独立 Worker 子线程 |
| 权限声明 | plugin.json 显式声明 |
| 数据访问 | 不能直接操作数据库，只能通过 API |
| 前端 UI | UI 代码运行在 Web Worker 沙箱 |