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	エージェントのステータスが変更されました	エージェントの完了を監視し、エラーを処理する

イベントペイロードの構造

{
  "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 UI を利用できます。

リソース

• 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 ハンドラーへの確実な配信、自動再試行、再生、レート制限、可観測性を提供します