​
Webhooks

Saat kamu membuat agent dengan webhook URL, Cursor akan mengirim request HTTP POST buat ngasih tahu kamu tentang perubahan status. Saat ini, cuma event statusChange yang didukung, khususnya ketika agent masuk ke state ERROR atau FINISHED.

​
Verifikasi webhook

Untuk memastikan permintaan webhook benar-benar dari Cursor, verifikasi tanda tangan yang disertakan di setiap permintaan:
Setiap permintaan webhook menyertakan header berikut:
  • X-Webhook-Signature – Berisi tanda tangan HMAC-SHA256 dengan format sha256=<hex_digest>
  • X-Webhook-ID – Pengenal unik untuk pengiriman ini (berguna untuk logging)
  • X-Webhook-Event – Jenis event (saat ini hanya statusChange)
  • User-Agent – Selalu di-set ke Cursor-Agent-Webhook/1.0

​
Verifikasi tanda tangan

Untuk memverifikasi tanda tangan webhook, hitung tanda tangan yang diharapkan lalu bandingkan dengan tanda tangan yang diterima: 
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
Selalu gunakan raw request body (sebelum parsing apa pun) saat menghitung tanda tangan.

​
Format payload

Payload webhook dikirim sebagai JSON dengan struktur berikut: 
{
  "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"
}
Perlu diingat, beberapa field bersifat opsional dan hanya akan disertakan jika tersedia.

​
Praktik terbaik

  • Verifikasi signature – Selalu verifikasi signature webhook untuk memastikan request berasal dari Cursor
  • Tangani retry – Webhook bisa dicoba ulang kalau endpoint-mu mengembalikan status error
  • Respons cepat – Kirim status 2xx secepat mungkin
  • Gunakan HTTPS – Selalu pakai URL HTTPS untuk endpoint webhook di production
  • Simpan payload mentah – Simpan payload webhook mentah untuk debugging dan verifikasi di kemudian hari