문서
Webhook 集成指南
Webhook 集成指南
学习如何设置 Webhook 将 Postion 与你的现有工具集成。自动化工作流、同步数据、构建自定义集成。
Webhook 允许你的外部应用在 Postion 站点上发生事件时接收实时通知。利用它来自动化工作流、与 CRM 同步数据、触发邮件等。
什么是 Webhook？
Webhook 是一种 HTTP 回调 — 当 Postion 上发生特定事件（如新订阅或购买）时，我们会向你指定的 URL 发送一个包含事件数据的 POST 请求。
设置 Webhook
第 1 步：创建 Webhook 端点
- 进入 控制台 → Webhooks
- 点击 「添加 Webhook」
- 输入你的端点 URL（如
https://your-app.com/api/postion-webhook） - 选择你要接收的事件
第 2 步：选择事件
| 事件 | 触发条件 | 数据内容 |
|---|---|---|
subscriber.created | 新订阅者注册 | 用户信息、方案详情 |
subscriber.updated | 订阅者更换方案 | 旧/新方案、用户信息 |
subscriber.deleted | 订阅者取消 | 用户信息、原因 |
post.published | 新文章发布 | 文章标题、URL、作者 |
purchase.completed | 完成单次购买 | 产品、金额、买家信息 |
payment.received | 订阅付款成功 | 金额、订阅者、方案 |
payment.failed | 付款失败 | 订阅者信息、失败原因 |
第 3 步：验证端点
创建 Webhook 后，Postion 会向你的 URL 发送验证请求。你的端点必须返回 200 OK 状态码以确认就绪。
Webhook 数据格式
所有 Webhook 数据遵循以下结构：
{
"event": "subscriber.created",
"timestamp": "2025-07-15T10:30:00Z",
"data": {
"id": "sub_abc123",
"email": "[email protected]",
"name": "Jane Doe",
"plan": "pro",
"site_id": "site_xyz789"
}
}安全：验证 Webhook 签名
每个 Webhook 请求都包含签名头（X-Postion-Signature），你应该验证它以确保请求确实来自 Postion。
import crypto from 'crypto';
function verifyWebhookSignature(payload, signature, secret) {
const hash = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return hash === signature;
}在生产环境中务必验证 Webhook 签名。永远不要信任未经验证的 Webhook 数据。
常见集成方案
与 CRM 同步
当新订阅者注册时，自动在 CRM 中创建联系人：
- 监听
subscriber.created事件 - 提取订阅者的邮箱和姓名
- 在你的 CRM（HubSpot、Salesforce 等）中创建或更新联系人
通过自定义服务发送欢迎邮件
通过你自己的邮件服务触发个性化欢迎邮件：
- 监听
subscriber.created事件 - 使用订阅者数据个性化邮件内容
- 通过你的邮件服务商（SendGrid、Mailgun 等）发送
Slack 通知
在关键事件发生时在 Slack 中收到通知：
- 创建 Slack Incoming Webhook URL
- 设置一个中间件接收 Postion Webhook
- 将格式化的消息转发到你的 Slack 频道
数据分析追踪
将事件记录到你的分析平台：
- 监听所有相关事件
- 转发到 Mixpanel、Amplitude 或你的自定义分析系统
- 构建面板追踪订阅者生命周期
重试策略
如果你的端点不可用，Postion 会以指数退避方式重试：
| 次数 | 延迟 |
|---|---|
| 第 1 次重试 | 1 分钟 |
| 第 2 次重试 | 5 分钟 |
| 第 3 次重试 | 30 分钟 |
| 第 4 次重试 | 2 小时 |
| 第 5 次重试 | 12 小时 |
5 次尝试失败后，Webhook 会被标记为异常，你会收到邮件通知。
故障排除
「Webhook 未收到事件」
- 确认你的端点 URL 是公开可访问的（不是
localhost） - 检查端点是否在 10 秒内返回
200状态码 - 确保在 Webhook 设置中选择了正确的事件
「签名无效」
- 确认你使用的是控制台中正确的 Webhook 密钥
- 验证你是在原始请求体（而非解析后的 JSON）上计算 HMAC
「事件到达顺序混乱」
由于网络状况，Webhook 可能乱序到达。使用 timestamp 字段来确定事件的真正顺序。
完整 API 参考请查看 公开 API 文档。 Webhook 系统架构的技术细节请查看 Webhooks 架构。