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