​
Webhooks

Wenn du einen Agenten mit einer Webhook-URL erstellst, sendet Cursor HTTP-POST-Anfragen, um dich über Statusänderungen zu informieren. Aktuell werden nur statusChange-Events unterstützt – konkret, wenn ein Agent den Status ERROR oder FINISHED erreicht.

​
Webhook-Verifizierung

Um sicherzustellen, dass Webhook-Requests wirklich von Cursor stammen, verifiziere die Signatur, die jedem Request beiliegt:
Jeder Webhook-Request enthält die folgenden Header:
  • X-Webhook-Signature – Enthält die HMAC-SHA256-Signatur im Format sha256=<hex_digest>
  • X-Webhook-ID – Eine eindeutige Kennung für diese Zustellung (nützlich fürs Logging)
  • X-Webhook-Event – Der Event-Typ (aktuell nur statusChange)
  • User-Agent – Immer gesetzt auf Cursor-Agent-Webhook/1.0

​
Signaturverifizierung

Um die Webhook-Signatur zu verifizieren, berechne die erwartete Signatur und vergleiche sie mit der empfangenen Signatur: 
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
Verwende beim Berechnen der Signatur immer den unveränderten Request-Body (vor jeglichem Parsing).

​
Payload-Format

Die Webhook-Payload wird als JSON mit der folgenden Struktur gesendet: 
{
  "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"
}
Beachte, dass einige Felder optional sind und nur enthalten sind, wenn sie verfügbar sind.

​
Best Practices

  • Signaturen überprüfen – Überprüfe immer die Webhook-Signatur, um sicherzugehen, dass die Anfrage von Cursor stammt
  • Retries handhaben – Webhooks können erneut zugestellt werden, wenn dein Endpoint einen Fehlerstatuscode zurückgibt
  • Schnell antworten – Sende so schnell wie möglich einen 2xx-Statuscode zurück
  • HTTPS verwenden – Verwende in Produktion immer HTTPS-URLs für Webhook-Endpoints
  • Rohpayloads speichern – Speichere die rohe Webhook-Payload für Debugging und spätere Verifizierung