WebhooksAPI
帖子发出与否，第一时间知道
只需注册一次 URL，每当投递有了结果，FoPost 就会调用它。每个事件都包含帖子 id、账号、平台、永久链接或错误信息，你的系统无需轮询就能做出响应。
POST /v1/webhooks
curl -X POST https://api.fopost.com/v1/webhooks \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspaceId": "9b2f6c1e-...",
"url": "https://yourbrand.com/hooks/social",
"events": ["delivery.published", "delivery.failed", "post.published", "post.failed"]
}'结果确定即触发
每个账号的投递对应一个事件，网络一确认或拒绝就立即发送。
带签名
每个请求都带有签名头，你可以验证它确实来自我们。
自动重试
非 2xx 响应会按退避策略重试，之后才会丢弃该事件。
事件
事件覆盖整个发布生命周期
当网络接受某个账号的投递时，delivery.published 会触发并附带永久链接。当投递无法发布时，delivery.failed 会触发并附带平台的错误信息。post.published 和 post.failed 则在所有账号都有结果后，每条帖子触发一次。
阅读 webhook 参考文档delivery.published
{
"event": "delivery.published",
"data": {
"postId": "7d3e0a52-...",
"postAccountId": "a3c5e7f9-...",
"accountId": "4a71d80b-...",
"platform": "linkedin",
"externalUrl": "https://linkedin.com/feed/update/..."
},
"timestamp": "2026-09-01T09:00:07Z"
}delivery.published
永久链接，可直接存储或从你的 CMS 回链。
delivery.failed
网络自己的错误信息，让你对症修复，而不是靠猜。
按工作区
一个 webhook 属于一个工作区，只能看到该工作区的帖子。
处理程序
app.post('/hooks/social', async (req, res) => {
const signature = req.header(SIGNATURE_HEADER) // header name is in the docs;
if (!verify(req.rawBody, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).end();
}
const { event, data } = req.body;
await queue.add(event, data);
res.status(200).end();
});签名头
使用创建时获得的密钥验证。如需轮换，重新创建即可。
带时间戳
timestamp 让你忽略过期的重放，并正确排列事件顺序。
按 id 幂等
重试会带有相同的事件 id，重复投递很容易丢弃。
列出端点
GET /v1/webhooks 显示每个 URL 及其订阅的事件。
按环境划分
为预发布环境注册单独的 URL，测试帖子永远不会打到生产环境。
webhooks 权限
管理端点需要单独的权限范围。只能发布的密钥无法添加端点。
关于 Webhooks 的常见问题解答
有哪些事件可用？
帖子、投递、账号、收件箱和自动化事件。delivery.published 和 delivery.failed 按账号各触发一次，因此发往三个网络的帖子最多会产生三个；post.published 和 post.failed 每条帖子触发一次。
如何验证 webhook？
创建 webhook 并保存响应中的密钥。每次调用时，用该密钥对原始请求体计算签名，并与签名头比对。
如果我的端点宕机了怎么办？
任何非 2xx 响应或超时都会按退避策略重试。尽快返回 2xx，在后台处理事件，就能稳稳留在时间窗口内。
可以只接收某一个账号的事件吗？
投递事件包含 accountId 和 platform，请在你这边筛选。Webhook 的范围是工作区，而不是单个账号。
能在不真正发布的情况下测试吗？
把 webhook 指向一个请求捕获 URL，并定时发布一条帖子到测试账号。所有环境中的事件看起来完全一样。
我一定需要 webhook 吗？
不需要。GET /v1/posts/:id/deliveries 可按需返回相同的状态。Webhook 只是省去了轮询。