Webhook

Webhook 是 Sofia 在帖子上线或失败时发起的 HTTP 调用。你可以用它把内容同步到电子表格、通知消息工具，或在 Zapier 或 n8n 中触发一个场景。

添加一个

• 1. 给它一个地址。一个公开的 https 地址，Sofia 会把事件发到那里。
• 2. 选择事件。post.published 和 post.failed。
• 3. 注册它。POST /v1/webhooks：签名密钥（whsec_…）只会出现在这次响应中。
• 4. 发送测试。POST /v1/webhooks/{id}/test 会发送一个 webhook.test 事件，与其他事件一样带有签名。

完整的请求详见 API 标签页：注册 Webhook。只有由你的应用创建的帖子才会被通知。

构建接收端

务必先发送一次测试并保存收到的请求体：它就是约定，比任何描述都更可靠。Sofia 以 POST 方式发送每个事件，格式为 JSON { id, type, createdAt, data }，并带有 Sofia-Event-Id、Sofia-Event-Type 和 Sofia-Signature 请求头。

• 验证签名。Sofia-Signature 的值为 t=<unix time>,v1=<hex>，其中 v1 是用你的密钥对 <t>.<raw body> 计算的 HMAC-SHA256。请对原始请求体计算，并拒绝过旧的时间戳。
• 尽快返回 `2xx`，之后再做处理：缓慢的接收端与宕机的接收端无从区分。
• 保持幂等。同一个事件可能到达两次：请根据 Sofia-Event-Id 去重。

Webhook 不再触发时

地址无法访问

Sofia 从自己的服务器发起调用：地址必须是公开的 https。重定向永远不会被跟随，10 秒没有响应即视为失败。

地址返回错误

任何非 2xx 的响应都会触发重试，分别在 1 分钟、5 分钟、30 分钟和 2 小时之后，最多重试 5 次。请先查看你自己的日志，再用 POST /v1/webhooks/{id}/test 重现。

帖子不是由你的应用创建的

Webhook 只通知由你的应用创建的帖子；在界面中创建的帖子不会触发它。

延伸阅读

Webhook 告诉你 Sofia 何时采取了行动。要让 Sofia 采取行动，请使用 Sofia API、sofia CLI 或 MCP 服务器（API 和 Agents 标签页），或者第三方集成。