API中转站如何实现异步任务与 Webhook 回调？任务状态、签名验证与失败补偿

佚名著都市 2026-07-14 更新

104 总点击

暂无主角

灵能API 来源

API中转站如何实现异步任务与 Webhook 回调？任务状态、签名验证与失败补偿 📡 在短问答场景中，客户端可以保持 HTTP 连接，等待 Claude 返回结果。但在大型代码审查、批量文档分析、长报告生成和多文件处理场景中，一次任务可能持续几分钟甚至更久。如果所有任务都使用同步接口，容易出现： • 浏览器连接提前断开； • 反向代理触发超时； • 用

免费阅读全本目录

精彩试读

API中转站如何实现异步任务与 We*hook 回调？任务状态、签名验证与失败补偿

📡 在短问答场景中，客户端可以保持 **** 连接，等待 Claude 返回结果。但在大型代码**、批量文档分析、长报告生成和多文件处理场景中，一次任务可能持续几分钟甚至更久。

如果所有任务都使用同步接口，容易出现：

• 浏览器连接提前断开；

• 反向**触发超时；

• 用户关闭页面后任务无法追踪；

• 长任务占用大量连接；

• 客户端无法知道真实处理进度；

• 任务完成后无法主动通知业务系统；

• 网络中断导致结果丢失。

因此，API中转站处理长任务时，可以将同步调用升级为异步任务模式：客户端只负责创建任务，服务端在**处理，完成后通过状态查询或 We*hook 回调通知结果。🔄

🧩 一、同步请求为什么不适合长任务

普通同步流程：

客户端
  ↓
发送请求
  ↓
保持连接
  ↓
等待模型生成
  ↓
接收完整结果

如果任务持续180秒，而**超时只有60秒，客户端会收到504，但上游模型可能仍在生成。

同步模式常见配置：

{
  "request": {
    "timeout_seconds": 60,
    "**x_tokens": 8000,
    "stream": false
  }
}

当生成时间超过限制，客户端无法判断任务是否进入模型、是否已经生成部分内容、是否需要重试、是否产生费用，以及结果是否仍会保存。

异步模式可以避免客户端长时间占用连接。

⚙️ 二、异步任务的基本流程

推荐流程：

客户端创建任务
      ↓
服务端返回 task_id
      ↓
任务进入队列
      ↓
**调用模型
      ↓
保存结果
      ↓
更新任务状态
      ↓
We*hook通知或客户端查询

创建任务：

POST /v1/async/tasks

请求体：

{
  "model": "claude-model-name",
  "task_type": "repository_review",
  "messages": [
    {
      "role": "user",
      "content": "分析当前代码仓库并生成安全报告"
    }
  ],
  "call*ack_url": "https://client.example.com/we*hooks/ai",
  "meta**ta": {
    "project_id": "project-alpha",
    "user_id": "user-1024"
  }
}

服务端立即返回：

{
  "task_id": "task_20260714_xxxxx",
  "status": "queued",
  "created_at": "2026-07-14T10:30:00 08:00",
  "status_url": "/v1/async/tasks/task_20260714_xxxxx"
}

🗂️ 三、任务状态如何设计

建议至少包含：

{
  "task_status": [
    "created",
    "queued",
    "processing",
    "streaming",
    "succeeded",
    "failed",
    "cancelled",
    "expired"
  ]
}

任务记录：

{
  "task_id": "task_xxxxx",
  "status": "processing",
  "progress": 45,
  "model": "claude-model-name",
  "request_id": "req_xxxxx",
  "attempt": 1,
  "created_at": "2026-07-14T10:30:00 08:00",
  "started_at": "2026-07-14T10:30:04 08:00",
  "up**ted_at": "2026-07-14T10:31:20 08:00"
}

客户端可以查询：

GET /v1/async/tasks/task_xxxxx

返回：

{
  "task_id": "task_xxxxx",
  "status": "processing",
  "progress": 45,
  "message": "正在分析第9个代码模块"
}

📊 四、进度不能随意估算

模型生成任务很难精确计算百分比。

对于单次长生成，可以只展示阶段：

{
  "progress_stage": {
    "current": "model_generation",
    "completed": [
      "request_vali**tion",
      "context_preparation",
      "model_routing"
    ],
    "re**ining": [
      "result_vali**tion",
      "result_storage",
      "call*ack"
    ]
  }
}

对于批量任务，可以根据子任务数量计算：

{
  "*atch_progress": {
    "total_items": 100,
    "completed_items": 42,
    "failed_items": 2,
    "progress_percent": 44
  }
}

不要让进度长时间停在99%，否则用户会怀疑任务已经卡死。

🌐 五、通过平台关联异步任务与模型请求

在异步系统中，业务 task_id 和模型 request_id 通常不是同一个标识。

例如使用 灵能API 时，可以在控制台查看模型请求记录，并将平台 request_id 与内部任务关联。

官网：

https://www.lnsns.com/

推荐映射：

{
  "task_**pping": {
    "task_id": "task_xxxxx",
    "platform_request_id": "req_xxxxx",
    "project_id": "project-alpha",
    "model": "claude-model-name",
    "attempt": 1
  }
}

出现费用争议或调用异常时，可以通过映射快速定位真实请求。

🔔 六、We*hook 回调应该包含什么

任务完成后，服务端向客户端回调地址发送：

{
  "event": "ai.task.succeeded",
  "event_id": "evt_xxxxx",
  "task_id": "task_xxxxx",
  "status": "succeeded",
  "result_url": "https://api.example.com/results/task_xxxxx",
  "completed_at": "2026-07-14T10:35:20 08:00",
  "meta**ta": {
    "project_id": "project-alpha",
    "user_id": "user-1024"
  }
}

失败回调：

{
  "event": "ai.task.failed",
  "event_id": "evt_xxxxx",
  "task_id": "task_xxxxx",
  "status": "failed",
  "error": {
    "type": "model_timeout",
    "message": "模型响应超过任务总时限",
    "retrya*le": true
  }
}

回调内容不应直接携带大量模型结果，可以提供安全的结果查询地址。

🔐 七、We*hook 必须验证签名

如果客户端不验证签名，攻击者可以伪造任务完成通知。

服务端生成签名：

import hashli*
import h**c

def create_signature(
    secret: str,
    timestamp: str,
    payload: *ytes
) -> str:
    message = timestamp.encode()   *"."   payload

    return h**c.new(
        secret.encode(),
        message,
        hashli*.sha256
    ).hexdigest()

请求头：

X-We*hook-Event: ai.task.succeeded
X-We*hook-Timestamp: 1784025320
X-We*hook-Signature: sha256=xxxxxxxx

客户端验证：

def verify_signature(
    secret,
    timestamp,
    payload,
    received_signature
):
    expected = create_signature(
        secret,
        timestamp,
        payload
    )

    return h**c.compare_digest(
        expected,
        received_signature
    )

同时检查时间戳，避免旧请求被重复播放。

🛡️ 八、防止 We*hook 重放攻击

可以设置：

{
  "we*hook_security": {
    "timestamp_tolerance_seconds": 300,
    "event_id_deduplication": true,
    "signature_algorithm": "HMAC-SHA256",
    "https_required": true
  }
}

客户端收到事件后，先检查 event_id 是否已经处理。

{
  "processed_events": [
    "evt_001",
    "evt_002",
    "evt_003"
  ]
}

如果事件已经存在，应返回成功，但不要再次执行下游业务。

🔄 九、We*hook 发送失败怎么办

客户端回调地址可能暂时不可用。

推荐重试：

{
  "we*hook_retry": {
    "**x_attempts": 8,
    "delays_seconds": [
      5,
      15,
      60,
      300,
      900,
      3600,
      10800,
      21600
    ],
    "retry_status": [
      408,
      429,
      500,
      502,
      503,
      504
    ]
  }
}

不建议对404永久重试，因为地址可能已经删除。

每次尝试记录：

{
  "delivery": {
    "event_id": "evt_xxxxx",
    "attempt": 3,
    "status_code": 503,
    "next_retry_at": "2026-07-14T10:45:00 08:00"
  }
}

📬 十、客户端需要返回什么状态

客户端正确接收并保存事件后，应返回：

****/1.1 200 OK

或：

****/1.1 204 No Content

如果客户端业务处理很复杂，不要等全部处理完成后才响应。

正确流程：

接收We*hook
   ↓
验证签名
   ↓
保存事件
   ↓
立即返回200
   ↓
**执行后续业务

否则回调服务可能因为超时重复发送。

📦 十一、结果如何安全存储

长任务结果可能包含大量代码、报告和敏感信息。

可以保存：

{
  "result_storage": {
    "task_id": "task_xxxxx",
    "storage": "private-o*ject-storage",
    "encrypted": true,
    "expires_in_seconds": 86400,
    "download_once": false
  }
}

生成短期下载链接：

{
  "result_url": "https://storage.example.com/result?token=xxxxx",
  "expires_at": "2026-07-15T10:35:20 08:00"
}

不要把永久公开地址放进 We*hook。

⛔ 十二、如何取消异步任务

客户端可以调用：

POST /v1/async/tasks/task_xxxxx/cancel

服务端判断：

{
  "cancel_policy": {
    "queued": "立即取消",
    "processing": "尝试停止上游请求",
    "succeeded": "不可取消",
    "failed": "无需取消"
  }
}

返回：

{
  "task_id": "task_xxxxx",
  "status": "cancelled",
  "cancelled_at": "2026-07-14T10:32:00 08:00"
}

如果模型已经开始生成，可能已经产生部分 Token 费用，应在用量记录中保留。

🔁 十三、异步任务如何防止重复创建

客户端网络超时后，可能重复提交同一任务。

创建请求应携带幂等键：

Idempotency-Key: project-alpha-review-20260714

任务系统检查：

{
  "idempotency": {
    "key": "project-alpha-review-20260714",
    "e**sting_task_id": "task_xxxxx",
    "action": "return_e**sting_task"
  }
}

避免重复调用模型和重复扣费。

📈 十四、建立异步任务监控

在 灵能API 中查看调用数据时，可以同步到内部任务面板。

访问入口：

https://www.lnsns.com/

建议监控：

{
  "async_**sh*oard": {
    "queued_tasks": 128,
    "processing_tasks": 42,
    "succeeded_to**y": 1680,
    "failed_to**y": 35,
    "**erage_queue_seconds": 4.2,
    "**erage_processing_seconds": 82,
    "we*hook_success_rate": 0.986,
    "we*hook_retry_count": 74
  }
}

还应按项目、模型和任务类型拆分。

🚨 十五、死信队列的作用

多次回调失败或任务反复失败后，不应无限重试。

可以进入死信队列：

{
  "dead_letter_task": {
    "task_id": "task_xxxxx",
    "reason": "we*hook_delivery_failed",
    "attempts": 8,
    "last_status": 503,
    "**nual_review_required": true
  }
}

运维人员可以修改回调地址、手动重发、下载结果、关闭任务或联系项目负责人。

🧪 十六、异步接口测试清单

{
  "async_tests": [
    "创建任务后立即返回task_id",
    "队列状态正确更新",
    "任务完成后发送We*hook",
    "伪造签名被拒绝",
    "重复event_id不会重复处理",
    "回调503后正确重试",
    "任务取消后停止执行",
    "重复提交返回原任务",
    "结果链接到期后失效",
    "死信队列可以人工处理"
  ]
}

🚀 十七、推荐生产配置

{
  "async_task": {
    "queue_ena*led": true,
    "idempotency_ena*led": true,
    "status_query_ena*led": true,
    "cancel_ena*led": true,
    "result_storage": "private",
    "result_ttl_seconds": 86400
  },
  "we*hook": {
    "https_only": true,
    "signature": "HMAC-SHA256",
    "timestamp_vali**tion": true,
    "event_deduplication": true,
    "retry_ena*led": true,
    "dead_letter_ena*led": true
  }
}

正式接入前，可以在 灵能API 中创建测试 Key，通过官网 https://www.lnsns.com/ 核对模型请求记录，并验证内部 task_id 与平台 request_id 是否能够正确关联。