Webhook
注册 webhook
注册 Sofia 以带签名 JSON 事件调用的 https URL，失败最多重试五次。密钥仅显示一次，最多 10 个。
注册 Webhook
注册一个公开的 https 地址和你想要的事件。签名密钥（whsec_…）只会出现在这次响应中。一个应用最多可以有 10 个 Webhook。
curl -X POST https://api.sofia-post.com/api/v1/webhooks \
-H "Authorization: Bearer $SOFIA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"url":"https://app.example.com/hooks/sofia","events":["post.published","post.failed"]}'事件
| 事件 | data |
|---|---|
post.published | postId、establishmentId、platform、publishedAt、permalink |
post.failed | postId、establishmentId、platform、error |
webhook.test | webhookId |
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。请对原始请求体验证，并拒绝过旧的时间戳：
import { createHmac, timingSafeEqual } from 'node:crypto';
const isSignedBySofia = (header, rawBody, secret) => {
const parts = Object.fromEntries(
(header ?? '').split(',').map((part) => part.trim().split('=', 2)),
);
const timestamp = Number(parts.t);
if (!Number.isInteger(timestamp) || typeof parts.v1 !== 'string') return false;
if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest();
const received = Buffer.from(parts.v1, 'hex');
return received.length === expected.length && timingSafeEqual(received, expected);
};投递与重试
- 返回
2xx即表示事件已送达。任何其他响应、重定向（从不跟随）或 10 秒无响应，都会在 1 分钟、5 分钟、30 分钟和 2 小时之后触发重试，最多重试 5 次。 - 同一个事件可能到达两次：请根据
Sofia-Event-Id去重。 - 请尽快响应，之后再处理事件。
授权
Authorizationstringheader必填你的个人密钥或 OAuth 访问令牌，以
Bearer <token>发送。
请求体
urlstring必填Sofia 调用的 https 地址。解析到私有、回环或链路本地地址的主机会被拒绝
eventsstring[]必填要接收的事件
响应
webhook 及其签名密钥，仅显示一次。
idstring必填webhook 的标识符
urlstring必填Sofia 调用的地址
eventsstring[]必填已订阅的事件
createdAtstring<date-time>必填webhook 的注册时间
secretstring必填为每次投递签名的 HMAC-SHA256 密钥（
Sofia-Signature）。仅此一次显示
这个页面对你有帮助吗？