《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 负载，以便调试和日后验证