Webhook Dokümantasyonu

    Şema olayları için gerçek zamanlı bildirimler

    Webhook Nedir?

    Webhook'lar, şemalar üretildiğinde, güncellendiğinde veya hata oluştuğunda uygulamanızın gerçek zamanlı bildirim almasını sağlar. API'mizi sürekli sorgulamak yerine webhook'lar veriyi sunucunuza anında iletir.

    Platform Desteği

    Webhook uyumlu tüm platformlarla çalışır

    Webhook'larımız, her platformla çalışan hibrit payload formatı kullanır. Payload; özel entegrasyonlar için yapılandırılmış veriler ve mesajlaşma platformları için zengin biçimlendirme içerir.

    Slack

    Slack Incoming Webhook URL'nizi kullanın. Mesajlar zengin biçim ve bloklarla görüntülenir.

    Discord

    Discord Webhook URL'nizi kullanın. text alanı temiz bir özet mesaj sağlar.

    Özel Endpoint

    Herhangi bir HTTP endpoint kullanın. Özel entegrasyonunuz için yapılandırılmış JSON payload'ını ayrıştırın.

    Webhook Kurulumu

    Webhook endpoint'inizi 3 basit adımda yapılandırın

    1

    Webhook endpoint oluşturun

    Sunucunuzda POST isteklerini alabilen bir HTTP endpoint oluşturun.

    2

    Proje Ayarlarından yapılandırın

    Proje Ayarları > Webhooks bölümüne gidin, endpoint URL'nizi ve isteğe bağlı secret bilgisini girin.

    3

    Webhook'unuzu test edin

    Endpoint'inizin doğru çalıştığını doğrulamak için "Test Webhook" düğmesini kullanın.

    Webhook Olayları

    Webhook bildirimlerini tetikleyen olaylar

    schema.generated

    Bir sayfa için şema başarıyla üretildiğinde veya yeniden üretildiğinde tetiklenir.

    schema.failed

    Şema üretimi başarısız olduğunda tetiklenir. Payload içinde hata detaylarını içerir.

    scan.completed

    Web sitesi taraması (crawl) başarıyla tamamlandığında tetiklenir. Taranan URL'ler ve yeni keşfedilen sayfalar hakkında bilgi içerir.

    scan.failed

    Web sitesi taraması (crawl) başarısız olduğunda tetiklenir. Sorunun ne olduğuna dair hata detaylarını içerir.

    project.email_notifications.toggled

    Bir proje için e-posta bildirim ayarı değiştirildiğinde tetiklenir.

    project.api_key.generated

    Bir proje için yeni API anahtarı oluşturulduğunda tetiklenir.

    project.api_key.deleted

    Bir projeden API anahtarı silindiğinde tetiklenir.

    project.scheduled_regeneration.toggled

    Bir proje için zamanlanmış yeniden üretim ayarı değiştirildiğinde tetiklenir.

    project.webhook.toggled

    Bir proje için ana webhook aç/kapat anahtarı kullanıldığında tetiklenir.

    job.completed

    Projeyle ilişkili herhangi bir arka plan işi başarıyla tamamlandığında tetiklenir.

    job.failed

    Projeyle ilişkili herhangi bir arka plan işi başarısız olduğunda tetiklenir.

    Webhook Payload

    Endpoint'inize gönderilen verinin yapısı

    {
  "event": "string",           // Event type (e.g., "schema.generated", "scan.completed")
  "timestamp": "string",       // ISO 8601 format (e.g., "2024-01-15T10:30:00.000Z")
  "projectId": "string",       // ID of the project
  "userId": "string",          // ID of the user who owns the project
  "text": "string",            // Plain text summary for all platforms

  // Optional fields, depending on the event type
  "jobId"?: "string",          // ID of the associated job, if any
  "pageId"?: "string",         // ID of the associated page, if any
  "status"?: "completed" | "failed", // Status for job-related events

  "data"?: {                   // Event-specific data
    // Example for "schema.generated" / "schema.failed"
    "pageUrl"?: "string",
    "schemaVersionId"?: "string",
    "error"?: "string",        // For failed events

    // Example for "scan.completed" / "scan.failed"
    "baseUrl"?: "string",
    "error"?: "string",        // For failed events

    // Example for "project.email_notifications.toggled"
    "setting"?: "string",      // e.g., "jobCompletion"
    "enabled"?: boolean,       // Setting state

    // Example for "project.api_key.generated" / "project.api_key.deleted"
    "apiKeyName"?: "string",
    "apiKeyId"?: "string",
    "lastCharacters"?: "string",

    // Example for "project.scheduled_regeneration.toggled"
    "frequency"?: "weekly" | "monthly",

    // Add any event-specific fields
    [key: string]: any
  },

  // Optional: Slack-specific rich formatting (ignored by non-Slack platforms)
  "blocks"?: Array<{           // Slack message blocks (optional, Slack only)
    type: string,
    text?: object,
    fields?: Array<any>
  }>
}

    Güvenlik ve İmza Doğrulama

    Webhook doğruluğunu HMAC imzalarıyla doğrulayın

    Webhook secret tanımlarsanız her webhook'u şu başlıkta gönderilen HMAC SHA-256 imzası ile imzalarız X-Webhook-Signature .

    Node.js Örneği:

    const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifyWebhook(payload, signature, YOUR_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});

    En İyi Uygulamalar

    • Secret tanımladıysanız imzayı daima doğrulayın
    • Hızlı şekilde 2xx durum kodu döndürün (5 saniye içinde)
    • Webhook verisini asenkron işleyin (kuyruk kullanın)
    • Yinelenen teslimatları yönetmek için idempotency uygulayın
    • Prod ortamında HTTPS endpoint kullanın

    Sorun Giderme

    Webhook olayları gelmiyor mu?

    • Endpoint'inizin herkese açık olduğundan emin olun
    • Sunucunuzun 2xx durum kodları döndürdüğünü kontrol edin
    • Güvenlik duvarınızın gelen isteklere izin verdiğinden emin olun
    • Yapılandırmayı doğrulamak için "Test Webhook" düğmesini kullanın

    İmza doğrulama başarısız mı oluyor?

    • Ham istek gövdesini kullandığınızdan emin olun (parse edilmiş JSON değil)
    • Secret bilgisinin birebir eşleştiğini kontrol edin (ekstra boşluk olmasın)
    • HMAC SHA-256 algoritmasını kullandığınızı doğrulayın
    Webhook Dokümantasyonu | Brandop