Skip to main content

Command Palette

Search for a command to run...

API

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