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 – sha256=<hex_digest> 形式の HMAC-SHA256 署名
  • 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"}

一部のフィールドは省略可能で、利用可能な場合にのみ含まれます。

ベストプラクティス

  • 署名を確認 – リクエストがCursorからのものであることを確認するため、Webhookの署名を必ず検証してください
  • 再試行に対応 – エンドポイントがエラーステータスコードを返すと、Webhookが再試行される場合があります
  • 速やかに応答 – できるだけ早く2xxステータスコードを返してください
  • HTTPSを使用 – 本番環境のWebhookエンドポイントには必ずHTTPS URLを使用してください
  • 生のペイロードを保存 – デバッグや将来の検証に備えて、Webhookの生のペイロードを保存してください