Webhook Entegrasyonu

Cvisioner, platformdaki kritik olaylar gerçekleştiğinde belirlediğiniz URL'e HTTP POST istekleri göndererek sizi bilgilendirir. Webhook altyapısı Workflow SDK üzerine kurulmuştur — bu sayede güvenilir teslimat, otomatik yeniden deneme ve idempotency garantisi sağlanır.

Desteklenen Olay Tipleri

Faturalama Olayları

Başvuru Olayları

İş İlanı Olayları

PayTR Ödeme Webhook'u

PayTR ödeme bildirimleri özel bir akış ile işlenir:

1. PayTR, ödeme sonucunu POST /api/webhooks/paytr adresine gönderir
2. Sunucu, gelen isteğin merchant_key ve merchant_salt kullanılarak oluşturulan HMAC-SHA256 imzasını doğrular
3. Doğrulama başarılıysa ödeme durumu güncellenir ve ilgili workflow tetiklenir
4. İdempotency: Aynı merchant_oid ile gelen mükerrer istekler, işlemin tekrarlanmasını önlemek için kontrol edilir

// PayTR HMAC doğrulama örneği
import { createHmac } from "crypto";

function verifyPayTRSignature(params: Record<string, string>, merchantKey: string, merchantSalt: string): boolean {
  const hashStr = `${params.merchant_oid}${merchantSalt}${params.status}${params.total_amount}`;
  const expectedHash = createHmac("sha256", merchantKey)
    .update(hashStr)
    .digest("base64");

  return expectedHash === params.hash;
}

Webhook Güvenliği

Tüm webhook istekleri X-Cvisioner-Signature başlığı ile imzalanır. Gelen isteklerin gerçekten Cvisioner'dan geldiğini doğrulamak için bu imzayı kontrol etmelisiniz:

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = createHmac("sha256", secret)
    .update(payload, "utf8")
    .digest("hex");

  return timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );
}

Dikkat: İmza doğrulamasında timingSafeEqual kullanarak timing attack'lardan korunun.

Yeniden Deneme Politikası

Webhook teslimatı başarısız olduğunda Workflow SDK otomatik olarak yeniden dener:

Başarılı yanıt: HTTP 200 durum kodu. Diğer tüm durum kodları başarısız sayılır ve yeniden deneme tetiklenir.

Örnek Payload

{
  "event": "application.status_changed",
  "data": {
    "application_id": "app_abc123",
    "job_id": "job_xyz789",
    "old_status": "pending",
    "new_status": "interview_scheduled",
    "updated_by": "user_def456"
  },
  "timestamp": "2025-02-08T12:00:00Z",
  "idempotency_key": "evt_unique_key_001"
}

Webhook URL Yapılandırması

1. Yönetim Paneli > Ayarlar > Webhook'lar bölümüne gidin
2. Yeni Webhook Ekle butonuna tıklayın
3. Hedef URL'inizi girin ve dinlemek istediğiniz olayları seçin
4. Oluşturulan Signing Secret değerini güvenli bir yere kaydedin