跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt

Use this file to discover all available pages before exploring further.

为门店新增 Webhook 端点。每个门店在所有通道下最多可配置 20 个 Webhook。 
POST /v1/actions/store/add-webhook
认证方式： API Key（需要 owner 或 admin 角色）

​
请求体

字段类型必需说明
storeIdstring是Store ID（Short ID 格式 STO_xxx）
channelstring是取值为 http、feishu、discord、telegram、slack 之一
urlstring是目标 Webhook URL（HTTPS；商户需确保 URL 与所选通道匹配）
eventsstring[]是订阅的事件类型 —— 例如 ["order.completed", "refund.succeeded"]。空数组表示不向该 Webhook 触发任何事件。
testModeboolean是true = 仅对测试交易触发；false = 仅对生产交易触发
secretstring | null否通道特定凭据（如 Telegram 的 chat_id）。以不透明字符串形式存储。

​
请求示例

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

// 标准 HTTPS Webhook（RSA 签名信封）
const { webhook } = await client.webhooks.add({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  channel: "http",
  url: "https://example.com/webhooks/pancake",
  events: ["order.completed", "refund.succeeded"],
  testMode: false,
});

​
成功响应 (200)

{
  "data": {
    "webhook": {
      "id": "11111111-2222-3333-4444-555555555555",
      "storeId": "uuid-of-store",
      "channel": "http",
      "url": "https://example.com/webhooks/pancake",
      "events": ["order.completed", "refund.succeeded"],
      "testMode": false,
      "secret": null,
      "createdAt": "2026-05-07T00:00:00.000Z",
      "updatedAt": "2026-05-07T00:00:00.000Z"
    }
  }
}
返回的 webhook.id 是 UUID，而非 Short ID —— Webhook ID 不属于 IdPrefix 范围。请将其原样传入 update-webhook 与 remove-webhook。

​
响应字段

字段类型说明
idstringWebhook UUID
storeIdstring所属门店的 UUID
channelstringWebhook 通道（http、feishu、discord、telegram 或 slack）
urlstring目标 Webhook URL
eventsstring[]订阅的事件类型
testModebooleantrue 对测试交易触发，false 对生产交易触发
secretstring | null通道特定凭据（不透明字符串），未设置时为 null
createdAtstring创建时间戳（ISO 8601）
updatedAtstring最后更新时间戳（ISO 8601）

​
错误响应

状态码说明
400channel 不在允许列表、url 不是合法 HTTPS URL、events 不是字符串数组、secret 不是 string/null，或门店已达 20 个 Webhook 上限
403调用方不是该门店的 owner 或 admin