​
Webhook’ler

Bir agent’ı bir webhook URL’siyle oluşturduğunda, Cursor durum değişiklikleri hakkında seni bilgilendirmek için HTTP POST istekleri gönderir. Şu anda yalnızca statusChange olayları desteklenir; özellikle bir agent ERROR veya FINISHED durumuna geçtiğinde.

​
Webhook doğrulaması

Webhook isteklerinin gerçekten Cursor’dan geldiğinden emin olmak için, her istekle birlikte gelen imzayı doğrula:

​
Headers

Her webhook isteği aşağıdaki header’ları içerir:
  • X-Webhook-Signature – sha256=<hex_digest> formatında HMAC-SHA256 imzasını içerir
  • X-Webhook-ID – Bu teslimat için benzersiz bir tanımlayıcı (loglama için yararlı)
  • X-Webhook-Event – Olay türü (şu anda yalnızca statusChange)
  • User-Agent – Her zaman Cursor-Agent-Webhook/1.0 olarak ayarlanır

​
İmza doğrulama

Webhook imzasını doğrulamak için, beklenen imzayı hesapla ve alınan imzayla karşılaştır: 
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
İmzayı hesaplarken her zaman ham istek gövdesini (herhangi bir parse işleminden önce) kullan.

​
Yük biçimi

Webhook yükü aşağıdaki yapıda JSON olarak gönderilir: 
{
  "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"
}
Bazı alanlar isteğe bağlıdır ve yalnızca mevcut olduklarında dahil edilir.

​
En iyi uygulamalar

  • İmzaları doğrula – İsteğin Cursor’dan geldiğinden emin olmak için webhook imzasını her zaman doğrula
  • Yeniden denemeleri ele al – Uç noktan hata durum kodu döndürürse webhooks yeniden denenebilir
  • Hızlı yanıt ver – Mümkün olan en kısa sürede 2xx durum kodu döndür
  • HTTPS kullan – Üretimde webhook uç noktaları için her zaman HTTPS URL’leri kullan
  • Ham payload’ları sakla – Hata ayıklama ve ilerideki doğrulamalar için ham webhook payload’ını sakla