cursor-webhooks

Cursor Webhooks

适用场景

• 设置 Cursor Cloud Agent webhook 处理程序
• 调试签名验证失败问题
• 了解 Cursor webhook 事件类型和负载
• 处理 Cloud Agent 状态变更事件（ERROR、FINISHED）

必备代码（请使用）

Cursor 签名验证（JavaScript）

const crypto = require('crypto');

function verifyCursorWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !secret) return false;

  // Cursor sends: sha256=xxxx
  const [algorithm, signature] = signatureHeader.split('=');
  if (algorithm !== 'sha256') return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false;
  }
}

Express Webhook 处理程序

const express = require('express');
const app = express();

// CRITICAL: Use express.raw() - Cursor requires raw body for signature verification
app.post('/webhooks/cursor',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature'];
    const webhookId = req.headers['x-webhook-id'];
    const event = req.headers['x-webhook-event'];

    // Verify signature
    if (!verifyCursorWebhook(req.body, signature, process.env.CURSOR_WEBHOOK_SECRET)) {
      console.error('Cursor signature verification failed');
      return res.status(401).send('Invalid signature');
    }

    // Parse payload after verification
    const payload = JSON.parse(req.body.toString());

    console.log(`Received ${event} (id: ${webhookId})`);

    // Handle status changes
    if (event === 'statusChange') {
      console.log(`Agent ${payload.id} status: ${payload.status}`);

      if (payload.status === 'FINISHED') {
        console.log(`Summary: ${payload.summary}`);
      } else if (payload.status === 'ERROR') {
        console.error(`Agent error for ${payload.id}`);
      }
    }

    res.json({ received: true });
  }
);

Python 签名验证（FastAPI）

import hmac
import hashlib
from fastapi import Request, HTTPException

def verify_cursor_webhook(body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header or not secret:
        return False

    # Cursor sends: sha256=xxxx
    parts = signature_header.split('=')
    if len(parts) != 2 or parts[0] != 'sha256':
        return False

    signature = parts[1]
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()

    # Timing-safe comparison
    return hmac.compare_digest(signature, expected)

常见事件类型

事件类型	描述	常见使用场景
statusChange	Agent 状态已变更	监控 Agent 完成状态、处理错误

事件负载结构

{
  "event": "statusChange",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "id": "agent_123456",
  "status": "FINISHED",  // or "ERROR"
  "source": {
    "repository": "https://github.com/user/repo",
    "ref": "main"
  },
  "target": {
    "url": "https://github.com/user/repo/pull/123",
    "branchName": "feature-branch",
    "prUrl": "https://github.com/user/repo/pull/123"
  },
  "summary": "Updated 3 files and fixed linting errors"
}

环境变量

# Your Cursor webhook signing secret
CURSOR_WEBHOOK_SECRET=your_webhook_secret_here

本地开发

若要在本地测试 webhook，请安装 Hookdeck CLI：

然后启动隧道：

npx hookdeck-cli listen 3000 cursor --path /webhooks/cursor

无需账号。提供本地隧道和 Web 界面，可用于检查请求。

资源

• overview.md - Cursor webhook 的介绍和事件类型
• setup.md - 在 Cursor 控制面板中配置 webhook
• verification.md - 签名验证详情和注意事项
• examples/ - 各框架的可运行示例

推荐：webhook-handler-patterns

若要实现适用于生产环境的 webhook 处理，也请使用 webhook-handler-patterns 技能：

• 处理程序顺序
• 幂等性
• 错误处理
• 重试逻辑

相关技能

• stripe-webhooks - Stripe webhook 处理
• github-webhooks - GitHub webhook 处理
• shopify-webhooks - Shopify webhook 处理
• openai-webhooks - OpenAI webhook 处理
• webhook-handler-patterns - 幂等性、错误处理、重试逻辑
• hookdeck-event-gateway - 可替代队列的 webhook 基础设施——为 webhook 处理程序提供可靠投递、自动重试、重放、速率限制和可观测性