Webhook 接入指南 · Worth Asking

准备接收地址

准备一个由你管理的公网 HTTPS 地址。它接收 Worth Asking 事件、验证签名，并在保存回执后返回响应。

已有接收端？确认它支持 POST、使用原始请求字节验签，并在持久化存储中按事件 ID 去重。填写包含路径的最终地址；系统不会跟随重定向。

接收地址示例

https://your-receiver.example/hook

还没有接收端？部署示例项目

可下载的 Cloudflare Worker 项目包含接收端、验签器、数据库结构和 README。需要 Node.js 22 或更新版本、npm，以及可使用 Workers 和 D1 的 Cloudflare 账户，用量与费用按你的账户计算。

下载接收端示例（.zip）

在下载文件所在的目录运行以下命令，登录用于托管接收端的 Cloudflare 账户。

创建接收端项目

unzip worthasking-webhook-receiver.zip
cd worthasking-webhook-receiver
npm install
npx wrangler login
npx wrangler d1 create worthasking-webhook-receiver

将最后一条命令返回的 database_id 填入 wrangler.jsonc 的 database_id，保留 RECEIVER_DB 绑定名。然后创建回执表并部署：

建表并部署

npx wrangler d1 execute worthasking-webhook-receiver --remote --file schema.sql
npm run deploy

在部署输出的 Worker HTTPS 地址后加上 /hook。接收端会拒绝未签名请求；完成第 2 步的签名凭据配置后，才能通过连接测试。

示例项目只负责验签和记录回执。要发送聊天消息或运行动作，还需要按下文接入转发。

完成标志：拿到接收端最终的公网 HTTPS 地址。

保存地址与签名密钥

打开 Webhook 设置，填写地址，选择接收哪些事件、哪些问题。所有套餐均可为每个账户配置一个地址。

打开 Webhook 设置

选择“重要变化”“完整首份判断已就绪”，或两者都选。范围可包括关注的公共问题，或逐个选择有权限的私人问题。
建议先保留默认的事件信息与登录后查看链接。标题和简短摘要可选；私人事件信息与私人内容需要分别明确授权。
点击“保存草稿”。安全保存仅展示一次的签名密钥，以及“签名密钥”一行中的 key ID。两者都配置到接收端前，请保留当前页面。

使用示例项目时，在项目目录运行以下命令：第一个提示中粘贴签名密钥，第二个提示中粘贴 key ID。命令会将它们保存为 Cloudflare secrets，请勿写入源代码或日志。

设置接收端凭据

npx wrangler secret put WEBHOOK_SIGNING_SECRET
npx wrangler secret put WEBHOOK_KEY_ID

保存后通知仍关闭。如果遗失密钥，请在“签名与地址管理”中轮换，重新保存需要的私人授权，并在接收端配置新密钥和 key ID。

完成标志：接收端已保存对应的签名密钥与 key ID。

测试连接

点击“测试已保存地址”并确认。Worth Asking 会发送一条 webhook.test 合成事件，不包含真实研究内容。

示例接收端在验签成功并保存回执后返回 HTTP 204。先在 Worth Asking 确认测试通过，再从接收端项目核对已保存的回执：

核对已保存回执

npx wrangler d1 execute worthasking-webhook-receiver --remote --command "SELECT event_id, event_type, received_at FROM webhook_receipts ORDER BY received_at DESC LIMIT 10"

核对 event_type 为 webhook.test、received_at 为本次测试时间。测试应记录回执，不发送业务消息，也不改变研究。Worth Asking 将任意 2xx 响应视为已接收，但这不代表自动化动作已经完成。

测试和通知共用每个接收地址每分钟一次尝试的限额。如提示稍后再试，请等待后重试。

完成标志：当前配置测试通过，接收端能查到 webhook.test 回执。

启用后续通知

点击“启用通知”，确认已保存的范围。仅测试通过不会自动开启通知。

确认选定范围内有符合条件的问题。之后发布新的首份判断或重要变化时，打开“投递记录 → 详情 → 事件”，将其中的事件 ID 与接收端回执核对。如果没有新事件，也可能只是暂时没有需要通知的变化。

保存地址、事件、范围或内容的修改后，才会暂停投递并取消旧的待发送尝试。未保存的草稿不会改变当前投递。请测试并启用已保存的新版本。暂停会停止后续尝试；恢复后从新事件开始，不会补发暂停期间的积压事件。

完成标志：设置显示“已启用”，新产生且符合范围与权限的事件可以发送到接收端。

进一步接入

自行开发接收端、连接通知渠道，或排查连接问题时，展开查看。

事件字段与签名验证

研究事件使用 schema_version 1，type 为 first_view_ready 或 meaningful_change。默认仅含链接的结构如下（为演示数据）。测试事件使用 webhook.test，且不包含 question。

研究事件结构示例

{
  "schema_version": "1",
  "id": "event_example",
  "type": "meaningful_change",
  "occurred_at": "2026-09-08T08:00:00.000Z",
  "question": {
    "id": "question_example",
    "visibility": "public",
    "url": "https://worthasking.ai/account/notifications/event_example"
  },
  "change": {
    "id": "change_example"
  }
}

meaningful_change 包含 change.id，first_view_ready 包含 view.id。可选的 question.title 和 summary 各不超过 500 个字符，单次请求不超过 32 KiB。请校验完整版本结构，不要假定每类事件都有相同字段。

保留以下五个请求头。时间戳为 Unix 秒，签名为小写十六进制 HMAC-SHA256。

签名请求头

X-WorthAsking-Signature-Version: 1
X-WorthAsking-Key-Id: <your key ID>
X-WorthAsking-Timestamp: <Unix seconds>
X-WorthAsking-Event-Id: <root JSON id>
X-WorthAsking-Signature: <lowercase hex HMAC-SHA256>

优先使用示例中的 verifier.ts：将签名密钥按 base64url 解码，验证 timestamp + "." + 原始请求体字节。不要先解析 JSON 再序列化。拒绝超过五分钟的时间戳、未知密钥或版本、错误结构以及请求头与正文不一致的事件 ID，并保持接收端时钟准确。

重试保留相同 id 和正文，并刷新签名时间戳。返回响应前，将唯一事件 ID 与待执行任务一并持久化。仅验签不能防止重复执行业务动作。

转发到 n8n、Slack 或其他渠道

推荐路径：Worth Asking → 已验签接收端 → 持久化任务 → 自动化或通知渠道。常见 Slack、Teams、Discord、飞书和企业微信机器人地址要求各自的消息格式，不能直接接收这份事件 JSON。

在接收端将唯一事件 ID 与转发任务原子写入，成功后返回 2xx；网络转发另行执行。
使用 n8n 时，发布一个 POST Webhook 工作流并使用 Production URL，用独立凭据保护这段转发。webhook.test 仅进入连接检查。
将 id 用作去重键，question.url 用作查看详情链接。question.title 和 summary 可能不存在。限制重试次数，并单独记录下游结果。

n8n Webhook 官方文档

示例项目不包含转发执行器、渠道账户或开箱即用的 n8n 工作流。渠道凭据、消息模板与下游重试需要由你的集成管理。

内容、权限与链接访问

默认正文包含事件信息、不可读含义的 ID 与需要登录的链接。启用摘要后，接收端可以保留、转发标题和简短摘要。请确认目的地的受众有必要看到这些内容，并避免在自动化日志中记录私人正文。

私人问题需要逐个选择，未来新增的私人问题不会自动加入。发送前仍会核对当前权限。Webhook 不授予访问权，也不会采用首稿、占用名额、公开研究或变更账单。

通知链接需要登录并具有当前问题访问权，依赖从投递准备起保留 30 天的记录；账户删除或失去权限后可能提前失效。删除接收地址不会立即撤销所有已经发出的链接。

测试或投递遇到问题

401 / 403：核对当前 key ID、密钥、原始字节与接收端时钟。修复后重新测试已保存版本，再明确启用。
重定向或地址被拒绝：填写最终公网 HTTPS 地址，不能跳转到登录页、私网或 Worth Asking 自身。
429 / 5xx / 网络失败：检查接收服务与“投递记录”。研究事件在发布后 24 小时内最多尝试五次（含手动重试），限额可能延后尝试。
超时或结果待核查：单次请求最多等待 10 秒，可能已经到达接收端。先按事件 ID 核对回执，再检查下游动作。事件可能重复，也可能乱序到达。
无法启用：保存修改、测试当前版本，并补齐需要的私人授权。敏感更改可能要求重新登录，设置页会保留草稿。

需要帮助时，请提供事件 ID、状态和大致时间，不要附带签名密钥或私人研究内容。

获取帮助

接收端就绪，就可以连接了。

前往 Webhook 设置，保存、测试并启用。你可以随时暂停投递。

打开 Webhook 设置帮助与反馈