Webhooks 指南
设置 核心API 出站 webhook (X-Webhook-Signature）用于许可证和平台事件。
对于 Pay 付款 webhook 使用 支付商家 Webhooks。 对于镜像重定向签名，请参阅 镜像SDK.
概述
Webhooks 允许您在 LicenseChain 帐户中发生事件时通过以下方式接收实时通知
核心API (POST /v1/webhooks）。支付商家活动使用
支付商家 Webhooks;
镜像重定向使用 镜像SDK 签名流程。
你将学到什么
设置和配置
- 创建和管理 Webhook
- 配置 Webhook 端点
- 设置事件订阅
- Webhook 安全和签名
执行
- 接收 webhook 事件
- 验证 Webhook 签名
- 处理 webhook 失败
- 测试 webhook 端点
创建网络钩子
1. 创建Webhook端点
首先，在您的应用程序中创建一个可以接收来自 LicenseChain 的 POST 请求的 HTTP 端点。
// Express.js Example
app.post('/webhooks/licensechain', async (req, res) => {'{'}
const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
const payload = JSON.stringify(req.body);
// Verify signature (see Security section)
if (!verifySignature(payload, signature, timestamp, webhookSecret)) {'{'}
return res.status(401).send('Invalid signature');
{'}'}
// Process webhook event
const event = req.body;
console.log('Received event:', event.type, event.data);
res.status(200).send('OK');
{'}'});
2. 注册您的 Webhook
使用 LicenseChain API 注册您的 Webhook 端点。您需要提供 URL 并指定您想要接收哪些事件。
POST /v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{'{'}
"url": "https://your-app.com/webhooks/licensechain",
"events": ["license.created", "license.updated", "license.revoked"],
"secret": "optional-custom-secret"
{'}'}
笔记： 如果您不提供密钥，LicenseChain 会自动为您生成一个密钥。 请确保安全地存储此机密，因为您需要它来验证 Webhook 签名。
3. 可用活动
LicenseChain 支持以下 Webhook 事件：
安全和签名验证
Webhook 签名
所有 Webhook 请求都包含签名 X-Webhook-Signature 标头。
签名是使用您的 Webhook 密钥的原始请求正文的 HMAC-SHA256。始终验证使用 恒定时间比较 （例如。 crypto.timingSafeEqual）以防止定时攻击。标头值可以是原始十六进制或 sha256= 后面跟着十六进制；剥离 sha256= 在比较十六进制缓冲区之前添加前缀，以便长度匹配。
// Node.js Example (constant-time, supports sha256= prefix)
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {'{'}
if (!payload || !signature || !secret) return false;
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const received = String(signature).startsWith('sha256=') ? String(signature).slice(7) : String(signature);
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(received, 'hex');
if (a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
{'}'}
// In your webhook handler (use raw body for payload)
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody || JSON.stringify(req.body);
if (!verifySignature(payload, signature, webhookSecret)) {'{'}
return res.status(401).send('Invalid signature');
{'}'}
请求标头
LicenseChain 在每个 Webhook 请求中包含以下标头：
X-Webhook-Signature
请求体的HMAC-SHA256签名
X-Webhook-Timestamp
发送 Webhook 时的 Unix 时间戳
Content-Type
总是 application/json
Webhook 事件结构
所有 Webhook 事件都遵循一致的结构：
{'{'}
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "license.created",
"data": {'{'}
"id": "license-id",
"licenseKey": "ABC123...",
"userId": "user-id",
"productId": "product-id",
"status": "active",
"expiresAt": "2024-12-31T23:59:59Z",
"createdAt": "2024-01-01T00:00:00Z"
{'}'},
"timestamp": "2024-01-01T00:00:00Z",
"signature": "hmac-sha256-signature"
{'}'}
管理网络钩子
列出所有 Webhook
GET /v1/webhooks?page=1&limit=10 Authorization: Bearer YOUR_API_KEY
获取 Webhook 详细信息
GET /v1/webhooks/:id Authorization: Bearer YOUR_API_KEY
更新网络钩子
PUT /v1/webhooks/:id
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{'{'}
"url": "https://new-url.com/webhooks",
"events": ["license.created", "license.updated"]
{'}'}
删除网络钩子
DELETE /v1/webhooks/:id Authorization: Bearer YOUR_API_KEY
测试网络钩子
发送测试 Webhook
您可以测试您的 webhook 端点，而无需等待真实事件发生：
POST /v1/webhooks/:id/test Authorization: Bearer YOUR_API_KEY
这将使用示例负载将测试事件发送到您的 webhook URL。用它来验证您的端点是否正常工作。
查看 Webhook 日志
检查每个 Webhook 事件的传送状态和响应：
GET /v1/webhooks/:id/logs?page=1&limit=10 Authorization: Bearer YOUR_API_KEY
日志包括HTTP状态码、响应正文以及发送是否成功。
最佳实践
✅ 始终验证签名
切勿在未验证签名的情况下处理 Webhook 事件。这可确保请求来自 LicenseChain 并且未被篡改。
✅ 快速回复
您的 Webhook 端点应在 5 秒内响应。对于长时间运行的操作，请立即确认 Webhook 并异步处理。
✅ 处理幂等性
使用事件 ID 可以防止多次处理同一事件。存储已处理的事件 ID 并在处理前进行检查。
✅ 使用 HTTPS
始终对 Webhook 端点使用 HTTPS，以确保数据在传输过程中加密。
✅ 监控 Webhook 日志
定期检查 Webhook 日志以识别并修复传送问题。为失败的交付设置警报。
故障排除
Webhook 未接收事件
- • 验证您的 Webhook URL 是否可以从 Internet 访问
- • 检查您的端点是否返回 2xx 状态代码
- • 确保您订阅的事件确实发生
- • 检查 Webhook 日志是否存在传送错误
签名验证失败
- • 确保您使用正确的 Webhook 密钥
- • 验证您正在签署准确的请求正文（作为 JSON 字符串）
- • 检查您是否使用 HMAC-SHA256 算法
- • 确保正确读取标题（区分大小写）
超时错误
- • 优化您的 Webhook 处理程序以快速响应
- • 将繁重的处理移至后台作业
- • 立即返回200 OK并异步处理
下一步
现在您已经了解了 Webhooks，您可以：