签名验证
确保回调请求来自麟鸣服务器
每个 Webhook 请求头中携带 X-Kirin-Signature 签名，用于验证请求来源。签名使用 HMAC-SHA256 算法，密钥为你的 Webhook Secret。
验证步骤
- 获取请求体原始 JSON 字符串
- 使用 Webhook Secret 对请求体进行 HMAC-SHA256 签名
- 将计算结果与
X-Kirin-Signature对比 - 签名一致则通过验证，否则拒绝请求
验证示例 (Python)
import hmac
import hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
computed = hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(computed, signature)事件类型
麟鸣 Webhook 支持以下事件类型。
task.completed
异步任务处理完成（如风格生成、视频剪辑完成）
示例 Payload
{
"event": "task.completed",
"task_id": "task_abc123",
"status": "completed",
"result": {
"url": "https://cdn.kirinseek.com/results/abc123.jpg",
"duration_ms": 12340
},
"timestamp": "2025-06-25T10:30:00Z"
}task.failed
异步任务处理失败
示例 Payload
{
"event": "task.failed",
"task_id": "task_abc123",
"status": "failed",
"error": {
"code": "PROCESSING_ERROR",
"message": "图片无法解析，请检查格式"
},
"timestamp": "2025-06-25T10:30:15Z"
}task.progress
任务处理进度更新（可选订阅）
示例 Payload
{
"event": "task.progress",
"task_id": "task_abc123",
"status": "processing",
"progress": 45,
"timestamp": "2025-06-25T10:29:45Z"
}重试机制
如果你的服务器未返回 2xx 状态码，系统将按以下策略重试：
1 次立即重试
2 次等待 10 秒后重试
3 次等待 30 秒后重试
4 次等待 60 秒后重试
4 次重试后放弃。可在「用户后台 → Webhook 设置」查看失败日志。