​
Webhooks

Quand tu crées un agent avec une URL de webhook, Cursor envoie des requêtes HTTP POST pour te notifier des changements d’état. Actuellement, seuls les événements statusChange sont pris en charge, en particulier lorsque un agent passe à l’état ERROR ou FINISHED.

​
Vérification des webhooks

Pour t’assurer que les requêtes webhook proviennent bien de Cursor, vérifie la signature incluse avec chaque requête :

​
En-têtes

Chaque requête webhook inclut les en-têtes suivants :
  • X-Webhook-Signature – Contient la signature HMAC-SHA256 au format sha256=<hex_digest>
  • X-Webhook-ID – Un identifiant unique pour cette livraison (pratique pour les logs)
  • X-Webhook-Event – Le type d’événement (pour l’instant uniquement statusChange)
  • User-Agent – Toujours défini sur Cursor-Agent-Webhook/1.0

​
Vérification de la signature

Pour vérifier la signature du webhook, calcule la signature attendue et compare-la avec la signature reçue : 
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
Utilise toujours le corps brut de la requête (avant toute analyse) pour calculer la signature.

​
Format du payload

Le payload du webhook est envoyé en JSON avec la structure suivante : 
{
  "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": "Ajout de README.md avec les instructions d’installation"
}
Note que certains champs sont facultatifs et ne seront inclus que s’ils sont disponibles.

​
Bonnes pratiques

  • Vérifie les signatures – Vérifie toujours la signature du webhook pour t’assurer que la requête vient de Cursor
  • Gère les retentatives – Les webhooks peuvent être retentés si ton endpoint renvoie un code d’état d’erreur
  • Réponds rapidement – Renvoie un code d’état 2xx dès que possible
  • Utilise HTTPS – Utilise toujours des URL HTTPS pour les endpoints de webhook en production
  • Stocke les payloads bruts – Stocke le payload brut du webhook pour le débogage et de futures vérifications