​
Webhooks

Cuando creas un agente con una URL de webhook, Cursor enviará solicitudes HTTP POST para avisarte sobre cambios de estado. Actualmente, solo se admiten eventos statusChange, específicamente cuando un agente llega a un estado ERROR o FINISHED.

​
Verificación de webhooks

Para asegurarte de 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 para esta entrega (útil para el logging)
  • X-Webhook-Event – El tipo de evento (actualmente solo statusChange)
  • User-Agent – Siempre establecido en Cursor-Agent-Webhook/1.0

​
Verificación de la firma

Para verificar la firma del webhook, calcula la firma esperada y compárala con la 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 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
Usa siempre el cuerpo sin procesar de la solicitud (antes de cualquier parsing) al calcular la firma.

​
Formato del payload

El payload del webhook se envía como 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 cuando estén disponibles.

​
Mejores prácticas

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