Перейти к основному содержанию

​
Вебхуки

Когда ты создаёшь агента с URL вебхука, Cursor будет отправлять HTTP POST‑запросы, чтобы уведомлять о сменах статуса. Сейчас поддерживаются только события statusChange, в частности, когда агент переходит в состояния 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 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
Всегда используй необработанное тело запроса (до любого парсинга) при вычислении подписи.

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

Полезная нагрузка вебхука отправляется в формате JSON со следующей структурой: 
{
  "event": "изменениеСтатуса",
  "timestamp": "2024-01-15T10:30:00Z",
  "id": "bc_abc123",
  "status": "ЗАВЕРШЕНО",
  "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": "Добавлен README.md с инструкциями по установке"
}
Учти, что некоторые поля необязательны и будут включаться только при наличии.

​
Лучшие практики

  • Проверяй подписи – всегда проверяй подпись вебхука, чтобы убедиться, что запрос пришёл от Cursor
  • Обрабатывай повторы – вебхуки могут отправляться повторно, если твой эндпоинт возвращает код ошибки
  • Отвечай быстро – как можно скорее возвращай код 2xx
  • Используй HTTPS – в продакшене всегда используй HTTPS‑URL для эндпоинтов вебхуков
  • Сохраняй «сырой» payload – сохраняй «сырой» payload вебхука для отладки и последующей проверки
⌘I