Webhooks
了解如何将实时通知集成到您的应用程序中
什么是 webhooks?
Webhooks 是应用程序在发生某些事件时发送的自动消息。它们包含消息—或载荷—并发送到唯一的 URL（您的端点）。
与不断检查我们的 API 获取新数据（轮询）不同，webhooks 在事件发生时实时将数据推送到您的应用程序。这更高效并提供即时通知。
当用户在您的网站上提交调查或表单时，Ask Users 可以通过 webhook 立即通知您的应用程序，使您能够：
- 自动将数据同步到您的 CRM（Salesforce、HubSpot 等）
- 通过 Slack 或电子邮件向您的团队发送通知
- 触发应用程序中的自定义工作流程
- 实时更新数据库
- 将数据输入分析平台
Webhooks 如何工作
事件发生
用户在您的网站上提交调查或表单。Ask Users 捕获此事件并准备通知您的应用程序。
触发 webhook
Ask Users 检查为此事件配置了哪些 webhooks。如果您的 webhook 设置为接收此事件类型，我们会准备包含所有相关数据的载荷。
发送 HTTP POST 请求
我们向您的 webhook URL 发送 HTTP POST 请求，其中包含 JSON 格式的事件数据。请求包括安全标头（HMAC 签名）以验证真实性。
您的端点处理数据
您的应用程序接收 webhook，验证签名并处理数据。您可以将其存储在数据库中、触发通知、更新记录或执行任何自定义逻辑。
响应和重试
您的端点应在 30 秒内响应 2xx 状态码（通常为 200 OK）。如果我们没有收到成功响应，我们将自动重试交付最多 5 次，使用指数退避：
- 尝试 1：立即
- 尝试 2：1 分钟后
- 尝试 3：5 分钟后
- 尝试 4：15 分钟后
- 尝试 5：1 小时后
- 尝试 6：6 小时后
主要功能
安全交付
所有 webhooks 都使用 HMAC-SHA256 签名进行签名以验证真实性
自动重试
失败的交付会自动重试最多 5 次，使用指数退避
实时交付
当事件发生时，webhooks 立即触发，通常在毫秒内
事件去重
唯一的事件 ID 可防止重复处理，即使在重试期间也是如此
支持的事件
survey.response.created
提交新的调查响应时触发。包含完整的响应数据，包括所有答案、受访者信息和调查元数据。
form.submission.created
创建新表单提交时触发。包括所有表单字段数据、提交状态和表单配置详细信息。
快速入门
在仪表板中配置 webhook
1. 转到您的仪表板
2. 导航到设置 → Webhooks
3. 点击创建 Webhook
4. 输入您的端点 URL 并选择事件类型
5. 保存并复制您的密钥
测试您的 webhook
提交测试调查或表单以触发您的 webhook 并验证其正常工作。检查仪表板中的交付日志以查看请求和响应。
Webhook 参考实现
这是如何在应用程序中创建和验证 webhook 端点的完整示例：
// Node.js/Express example
const crypto = require('crypto');
app.post('/webhooks/askusers', (req, res) => {
const signature = req.headers['x-webhook-signature'];
// Verify signature (see security section)
if (!verifySignature(req.body, signature)) {
return res.status(401).send('Invalid signature');
}
// Process webhook
const { event_type, data } = req.body;
// Return 200 OK immediately
res.status(200).send('OK');
// Process async
processWebhookAsync(event_type, data);
});Webhook 载荷示例
这是 webhook 载荷的示例：
{
"event_type": "survey.response.created",
"event_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2025-01-15T10:30:00.000Z",
"data": {
"response": {
"id": "response-uuid",
"survey_id": "survey-uuid",
"response_data": {
"question-id-1": "Answer 1",
"question-id-2": "Answer 2"
},
"completion_status": "completed",
"created_at": "2025-01-15T10:30:00.000Z"
},
"survey": {
"id": "survey-uuid",
"title": "Product Feedback Survey"
}
}
}安全性与验证
始终验证 webhook 签名以确保请求来自 Ask Users。每个 webhook 都包含一个带有 HMAC-SHA256 签名的 X-Webhook-Signature 标头。.
验证示例 (Node.js)
const crypto = require('crypto');
function verifySignature(payload, signature) {
const secret = process.env.ASKUSERS_WEBHOOK_SECRET;
const payloadString = JSON.stringify(payload);
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payloadString)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}验证示例 (Python)
import hmac
import hashlib
import os
def verify_signature(payload: str, signature: str) -> bool:
secret = os.environ['ASKUSERS_WEBHOOK_SECRET']
expected_signature = hmac.new(
secret.encode('utf-8'),
payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected_signature)最佳实践
1. 快速响应
始终立即返回 200 OK，然后异步处理 webhook。将响应时间保持在 30 秒以下以避免超时。
2. 处理重复交付
使用 event_id 对事件进行去重。存储已处理的事件 ID 以防止重复处理。这很重要，因为重试可能会导致同一事件被多次交付。
3. 使用 HTTPS
在生产环境中始终对 webhook 端点使用 HTTPS URL，以确保数据安全并防止中间人攻击。
4. 监控交付日志
检查仪表板中的 webhook 交付日志以监控成功率并识别问题。日志显示完整的请求/响应以进行故障排除。
5. 实现正确的错误处理
将您的 webhook 处理逻辑包装在 try-catch 块中并记录错误。返回适当的 HTTP 状态码：200-299 表示成功，4xx 表示客户端错误（不会重试），5xx 表示服务器错误（将触发重试）。
无代码集成
不想编写代码？使用 Zapier 或 Make 的 webhooks：
- 在 Zapier 或 Make 中创建新的 "Catch Webhook" 触发器
- 复制提供的 webhook URL
- 在 Ask Users 中使用该 URL 创建 webhook
- 通过提交表单或调查进行测试
- 构建您的自动化工作流程！