《Cursor文檔》-Webhook

創建帶有 webhook URL 的智能體時，Cursor 會發送 HTTP POST 請求，通知你智能體的狀態變更。目前僅支持 statusChange 事件，即智能體進入 ERROR 或 FINISHED 狀態時。

Webhook 驗證¶

爲確認 webhook 請求確實來自 Cursor，請驗證每個請求附帶的簽名：

請求頭¶

每個 webhook 請求均包含以下請求頭：

X-Webhook-Signature – 包含 HMAC-SHA256 簽名，格式爲 sha256=<hex_digest>
X-Webhook-ID – 此次投遞的唯一標識符 (便於記錄日誌)
X-Webhook-Event – 事件類型 (目前僅爲 statusChange)
User-Agent – 始終設置爲 Cursor-Agent-Webhook/1.0

簽名驗證¶

要驗證 webhook 簽名，請計算預期簽名，並與收到的簽名進行比較：

const crypto = require("crypto");

function verifyWebhook(secret, rawBody, signature) {
  const expectedSignature =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  return signature === expectedSignature;
}

import hmac
import hashlib

def verify_webhook(secret, raw_body, signature):
    expected_signature = 'sha256=' + hmac.new(
        secret.encode(),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    return signature == expected_signature

計算簽名時，務必使用未經解析的原始請求體。

負載格式¶

webhook 負載以 JSON 格式發送，結構如下：

{
  "event": "statusChange",
  "timestamp": "2024-01-15T10:30:00Z",
  "id": "bc_abc123",
  "status": "FINISHED",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "url": "https://cursor.com/agents?id=bc_abc123",
    "branchName": "cursor/add-readme-1234",
    "prUrl": "https://github.com/your-org/your-repo/pull/1234"
  },
  "summary": "Added README.md with installation instructions"
}

請注意，某些字段爲可選字段，僅在可用時纔會返回。

最佳實踐¶

驗證簽名 – 始終驗證 webhook 簽名，確保請求來自 Cursor
處理重試 – 如果端點返回錯誤狀態碼，webhook 可能會重試
快速響應 – 儘快返回 2xx 狀態碼
使用 HTTPS – 生產環境中的 webhook 端點應始終使用 HTTPS URL
存儲原始負載 – 存儲原始 webhook 負載，以便調試和日後驗證