Вебхуки

При создании Agent с URL вебхука Cursor отправляет HTTP POST-запросы, уведомляя об изменениях статуса. Сейчас поддерживаются только события statusChange — когда Agent переходит в состояние ERROR или FINISHED.

Проверка вебхука

Чтобы убедиться, что запросы вебхука действительно поступают от Cursor, проверьте подпись в каждом запросе:

Заголовки

Каждый вебхук-запрос содержит следующие заголовки:

• X-Webhook-Signature – Содержит HMAC-SHA256-подпись в формате sha256=<hex_digest>
• X-Webhook-ID – Уникальный идентификатор этой доставки (полезен для ведения журналов)
• X-Webhook-Event – Тип события (сейчас поддерживается только statusChange)
• User-Agent – Всегда имеет значение Cursor-Agent-Webhook/1.0

Проверка подписи

Чтобы проверить подпись вебхука, вычислите ожидаемую подпись и сравните её с полученной:

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

Всегда используйте сырое тело запроса (до обработки) при вычислении подписи.

Формат полезной нагрузки

Полезная нагрузка вебхука отправляется в формате 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
• Обрабатывайте повторные попытки – Вебхуки могут отправляться повторно, если ваша конечная точка возвращает код ошибки
• Быстро отвечайте – Как можно скорее возвращайте код состояния 2xx
• Используйте HTTPS – Всегда используйте HTTPS URL для конечных точек вебхуков в продакшене
• Сохраняйте необработанную полезную нагрузку – Сохраняйте необработанную полезную нагрузку вебхука для отладки и последующей проверки