> ## 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 端点

> 管理 HTTP、飞书、Discord、Telegram 和 Slack 的 Webhook 投递端点

Pancake 支持每个门店配置多个 Webhook 端点，覆盖五种通道：标准 HTTPS（RSA 签名信封）、飞书、Discord、Telegram 和 Slack。每个端点都是 `store.store_webhooks` 中的一条独立记录，拥有各自的 URL、订阅事件列表，以及 `test`/`prod` 环境绑定。

## 通道

| 通道         | 载荷格式                                                      | 签名                                  | 备注                                |
| ---------- | --------------------------------------------------------- | ----------------------------------- | --------------------------------- |
| `http`     | JSON 信封 `{ id, eventType, eventId, storeId, mode, data }` | RSA-SHA256（`X-Waffo-Signature` 请求头） | 默认通道；保留原有 Webhook 契约。             |
| `feishu`   | 飞书交互式卡片                                                   | 无 — URL 携带 token                    | 中文标题文案，UTC+8 时间戳                  |
| `discord`  | Discord embed                                             | 无 — URL 携带 token                    | 英文文案，客户端本地时间戳                     |
| `telegram` | `sendMessage` 载荷（`text` HTML、`chat_id`）                   | 无 — URL 中携带 bot token               | 英文文案，UTC；`chat_id` 存放在 `secret` 中 |
| `slack`    | Attachments 载荷                                            | 无 — incoming-webhook URL 携带 token   | 英文文案，UTC                          |

## URL 域名

无论何种通道，系统均接受任意 HTTPS URL。商户需自行确保 URL 与所选通道的目标平台匹配 —— 如果在 `channel: "slack"` 下配置了 Discord URL，调度器会按 Slack attachments 格式编码载荷并发送给 Discord 端点，Discord 端会返回错误，并将该次失败记录在 `webhook_deliveries` 中。

## 同 URL 多 webhook

同一门店内允许将同一 URL 配置在多个 Webhook 下 —— Webhook 采用扇出模型，不同事件订阅、不同通道或不同 `testMode` 可共用一个 URL。每个 Webhook 独立投递，因此当多个 Webhook 投递到同一 URL 时，消费方需按 `(eventType, eventId)` 去重。

## 限制

每个门店在所有通道下最多可配置 **20 个 Webhook**。超出上限会返回 400。

## 列出 Webhook

不存在 `list-webhooks` 端点 —— 查询已配置的 Webhook 列表通过 GraphQL `Store.storeWebhooks`（按 `test_mode` 自动过滤环境）：

```graphql theme={"system"}
query GetStoreWebhooks($storeId: String!) {
  store(id: $storeId) {
    storeWebhooks {
      id
      channel
      url
      events
      testMode
      secret
      createdAt
    }
  }
}
```

## 端点

<CardGroup cols={3}>
  <Card title="新增 Webhook" icon="plus" href="/zh/api-reference/endpoints/webhooks/add-webhook">
    为门店配置新的 Webhook 端点。
  </Card>

  <Card title="更新 Webhook" icon="pen" href="/zh/api-reference/endpoints/webhooks/update-webhook">
    修改 Webhook 的 URL、事件列表或 secret。
  </Card>

  <Card title="移除 Webhook" icon="trash" href="/zh/api-reference/endpoints/webhooks/remove-webhook">
    硬删除 Webhook（保留历史记录）。
  </Card>
</CardGroup>