事件类型
| Event | Description |
|---|---|
email.sent |
邮件已发送时 |
email.delivered |
邮件已送达收件人时 |
email.opened |
收件人打开邮件时 |
email.clicked |
收件人点击邮件中的链接时 |
email.bounced |
邮件被退回时 |
email.complained |
收件人举报为垃圾邮件时 |
subscriber.created |
新订阅者被添加时 |
subscriber.unsubscribed |
订阅者取消订阅时 |
campaign.sent |
活动开始发送时 |
campaign.completed |
活动发送完成时 |
载荷格式
所有Webhook请求包含以下格式的JSON载荷:
{
"event": "email.opened",
"timestamp": "2026-01-10T12:00:00+00:00",
"data": {
"campaign_id": 123,
"campaign_uuid": "abc-123...",
"campaign_name": "January Newsletter",
"subscriber_id": 456,
"subscriber_uuid": "def-456...",
"subscriber_email": "user@example.com",
"ip_address": "1.2.3.4",
"user_agent": "Mozilla/5.0...",
"occurred_at": "2026-01-10T12:00:00+00:00"
}
}请求头
| Header | Description |
|---|---|
Content-Type |
application/json |
X-Webhook-ID |
Webhook UUID |
X-Webhook-Event |
事件类型（例: email.opened） |
X-Webhook-Signature |
HMAC-SHA256签名 |
签名验证
为验证Webhook请求的真实性，请验证X-Webhook-Signature头。签名是使用Webhook密钥和请求正文生成的HMAC-SHA256哈希。
PHP示例
<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'your_webhook_secret';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
die('Invalid signature');
}
$data = json_decode($payload, true);
// Process the event...Node.js示例
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}
// Express.js example
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
if (!verifySignature(payload, signature, 'your_secret')) {
return res.status(401).send('Invalid signature');
}
// Process the event...
res.status(200).send('OK');
});重试策略
- • Webhook发送失败时（非2xx响应），不会自动重试。
- • 连续5次失败后，Webhook将自动禁用。
- • 被禁用的Webhook可以在仪表盘中重新启用。
- • 响应时间必须在10秒以内。
最佳实践
- • 始终验证签名以确认请求的真实性。
- • Webhook处理应尽快完成（5秒以内）。
- • 耗时较长的任务请放入队列，并立即返回200 OK。
- • 使用HTTPS端点安全传输数据。