Webhooks

Webhook 允许您在 FeedbackPulse 租户中发生事件时接收实时 HTTP 通知。

---

设置

通过仪表板

1. 前往设置 > 集成
2. 输入您的 Webhook URL
3. 选择要订阅的事件
4. 可选：设置用于 HMAC 签名验证的密钥
5. 保存

通过 API

PUT /api/v2/webhooks/config

{
  "url": "https://your-app.com/webhooks/feedbackpulse",
  "events": ["submission.created", "submission.status_changed"],
  "secret": "your_shared_secret"
}

---

Webhook 载荷

当事件发生时，FeedbackPulse 会向您的 URL 发送 POST 请求：

{
  "event": "submission.created",
  "timestamp": "2024-03-15T10:30:00Z",
  "data": {
    "id": 42,
    "campaign_id": 1,
    "star_rating": 5,
    "text_feedback": "Love this product!",
    "customer_name": "Jane Doe",
    "status": "pending"
  }
}

请求头

Content-Type: application/json
X-FeedbackPulse-Signature: sha256=abc123...
X-FeedbackPulse-Event: submission.created

---

签名验证

如果您设置了 webhook 密钥，请验证签名：

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_FEEDBACKPULSE_SIGNATURE'];
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

---

支持的端点

FeedbackPulse 会自动检测并为以下服务格式化载荷：

服务	URL 模式	格式
Slack	hooks.slack.com/*	Slack Block Kit 格式
Discord	discord.com/api/webhooks/*	Discord 嵌入格式
自定义	任意 HTTPS URL	原始 JSON 载荷

---

SSRF 防护

Webhook URL 会经过验证以防止服务端请求伪造：

• localhost、127.0.0.1、0.0.0.0 被阻止
• 私有 IP 范围（10.x、172.16-31.x、192.168.x）被阻止
• 仅允许公共 HTTPS URL

---

Webhook 日志

查看投递历史：

通过仪表板

设置 > 集成 > Webhook 日志

专属的 Webhook 日志页面也可通过 /webhooks/logs 访问，提供完整的投递历史、响应详情及筛选选项。可按事件类型、状态码和日期范围筛选，并查看每次投递尝试的完整请求载荷和响应体。

管理员 Webhook 日志查看器

超级管理员可通过 /admin/webhook-logs 访问平台级 webhook 日志查看器，可了解所有租户的 webhook 投递情况，便于诊断集成问题和监控平台健康状态。

通过 API

GET /api/v2/webhooks/logs

每条日志记录显示：

• 事件类型
• URL
• 响应码
• 发送的载荷
• 响应体
• 时间戳

---

后续步骤

• Webhook 事件参考