Skip to main content

Command Palette

Search for a command to run...

API

Webhooks

Cuando creas un agente con una URL de webhook, Cursor enviará solicitudes HTTP POST para notificarte de los cambios de estado. Actualmente, solo se admiten eventos statusChange, en concreto cuando un agente alcanza el estado ERROR o FINISHED.

Verificación de webhooks

Para verificar que las solicitudes de webhook provienen realmente de Cursor, verifica la firma incluida en cada solicitud:

Encabezados

Cada solicitud de webhook incluye los siguientes encabezados:

  • X-Webhook-Signature – Contiene la firma HMAC-SHA256 con el formato sha256=<hex_digest>
  • X-Webhook-ID – Un identificador único de esta entrega (útil para el registro)
  • X-Webhook-Event – El tipo de evento (actualmente, solo statusChange)
  • User-Agent – Siempre se establece como Cursor-Agent-Webhook/1.0

Verificación de firma

Para verificar la firma del webhook, calcula la firma esperada y compárala con la firma recibida:

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

Usa siempre el cuerpo sin procesar de la solicitud (antes de analizarlo) al calcular la firma.

Formato del payload

El payload del webhook se envía en formato JSON con la siguiente estructura:

{  "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"}

Ten en cuenta que algunos campos son opcionales y solo se incluirán si están disponibles.

Mejores prácticas

  • Verifica las firmas – Verifica siempre la firma del webhook para asegurarte de que la solicitud proviene de Cursor
  • Gestiona los reintentos – Los webhooks pueden volver a enviarse si tu endpoint devuelve un código de estado de error
  • Responde rápidamente – Devuelve un código de estado 2xx lo antes posible
  • Usa HTTPS – Usa siempre URL HTTPS para los endpoints de webhook en producción
  • Almacena los payloads sin procesar – Almacena el payload sin procesar del webhook para depuración y verificaciones futuras