​
Webhooks

当你为 agent 配置 webhook URL 时，Cursor 会通过 HTTP POST 请求通知状态变更。目前仅支持 statusChange 事件，即当 agent 进入 ERROR 或 FINISHED 状态时触发。

​
Webhook 验证

为确保 webhook 请求确实来自 Cursor，请验证每个请求附带的签名：

​
Headers

每个 webhook 请求都包含以下 headers：
  • 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 载荷，便于调试和后续验证