Pular para o conteúdo principal

Webhooks

Quando você cria um agente com uma URL de webhook, o Cursor envia requisições HTTP POST para te avisar sobre mudanças de status. No momento, apenas eventos statusChange são suportados, especificamente quando um agente entra nos estados ERROR ou FINISHED.

Verificação de webhook

Pra garantir que as requisições de webhook são de fato do Cursor, verifica a assinatura incluída em cada requisição:

Headers

Cada requisição de webhook inclui os seguintes headers:
  • X-Webhook-Signature – Contém a assinatura HMAC-SHA256 no formato sha256=<hex_digest>
  • X-Webhook-ID – Um identificador único pra essa entrega (útil pra logs)
  • X-Webhook-Event – O tipo de evento (no momento, apenas statusChange)
  • User-Agent – Sempre definido como Cursor-Agent-Webhook/1.0

Verificação de assinatura

Pra verificar a assinatura do webhook, calcula a assinatura esperada e compara com a assinatura recebida:
const crypto = require('crypto');

function verifyWebhook(secret, rawBody, signature) {
  const assinaturaEsperada = '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
Sempre usa o corpo cru da requisição (antes de qualquer parsing) ao calcular a assinatura.

Formato do payload

O payload do webhook é enviado em JSON com a seguinte estrutura:
{
  "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": "README.md adicionado com instruções de instalação"
}
Observa que alguns campos são opcionais e só serão incluídos quando estiverem disponíveis.

Melhores práticas

  • Verifica assinaturas – sempre verifica a assinatura do webhook pra garantir que a requisição é do Cursor
  • Lida com novas tentativas – webhooks podem ser reenviados se teu endpoint retornar um código de status de erro
  • Responde rápido – retorna um código de status 2xx o mais rápido possível
  • Usa HTTPS – sempre usa URLs HTTPS pros endpoints de webhook em produção
  • Armazena payloads brutos – armazena o payload bruto do webhook pra depuração e verificação futura
I