精彩片段

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 是否能夠正確關聯。