Webhook 集成

Webhook 允许您在特定事件发生时接收实时通知。

概述

支持的 Webhook 事件：

• 异步任务完成
• 监控预警触发
• 账户余额预警

配置 Webhook

1. 在控制台添加 Webhook URL

进入 设置 > Webhook，添加您的接收地址。

2. 选择订阅事件

选择需要接收通知的事件类型。

3. 获取签名密钥

保存签名密钥，用于验证请求来源。

Webhook 请求格式

POST /your-webhook-endpoint
Content-Type: application/json
X-Signature: sha256=xxxxxx
X-Timestamp: 1704067200

{
  "event": "task.completed",
  "data": {
    "taskId": "task_abc123",
    "status": "completed",
    "result": {...}
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

签名验证

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return `sha256=${expected}` === signature;
}

// Express 示例
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // 处理事件
  console.log('Event:', req.body.event);
  
  res.status(200).send('OK');
});

重试机制

如果您的服务未返回 2xx 响应，我们将重试：

• 第 1 次重试：1 分钟后
• 第 2 次重试：5 分钟后
• 第 3 次重试：30 分钟后

最佳实践

• 快速返回 200 响应，异步处理事件
• 实现幂等处理，避免重复消费
• 验证签名，确保请求来源可信