Webhook’lar (Tetikleyiciler)

Bir arama tamamlandığında, yeni bir kontak oluştuğunda ya da biri “beni aramayın” dediğinde — Purvisor’ı sürekli sorgulamak yerine, olay olur olmaz Purvisor sizin belirlediğiniz adrese bir HTTP POST gönderir. Buna outbound webhook (giden webhook) denir ve Zapier “Trigger” adımlarının, Make “Watch” modüllerinin altında çalışan mekanizma tam olarak budur. Sonuç: bir Zap’ı açtığınız anda Purvisor arka planda otomatik abone olur, kapattığınız anda aboneliği düşer — tek satır kod yazmadan.

REST-hook yaşam döngüsü

Zapier ve Make “REST hook” modelini kullanır: platform, aboneliği sizin adınıza otomatik yönetir. Bir “abonelik” (subscription), tek bir olayı (event) tek bir hedef URL’e (targetUrl) bağlayan kayıttır — Purvisor’ın telefon rehberindeki “şu olay olursa şu numarayı ara” satırı gibi düşünün.

Zap / senaryo AÇILIR
        ↓
Platform → POST /api/v1/hooks   (abone ol; secret'ı saklar)
        ↓
Olay gerçekleşir (örn. call.completed)
        ↓
Purvisor → POST targetUrl   (imzalı JSON zarfı)
        ↓
Zap / senaryo KAPANIR
        ↓
Platform → DELETE /api/v1/hooks/{id}   (aboneliği kaldır)

Bir olay için birden çok aboneliğiniz olabilir (örneğin aynı call.completed’ı hem Zapier’e hem kendi sunucunuza gönderin). Her abonelik bağımsız çalışır ve kendi imza secret’ına sahiptir.

Abone ol — POST /api/v1/hooks

Bir olayı bir hedef URL’e bağlar. Zapier/Make bunu Zap açıldığında otomatik çağırır; kendi entegrasyonunuzu kuruyorsanız elle çağırırsınız.

İstek gövdesi

curl -X POST https://app.purvisor.ai/api/v1/hooks \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "call.completed",
    "targetUrl": "https://ornek.com/purvisor/webhook",
    "source": "custom"
  }'

Başarılı yanıt — HTTP 201

{
  "id": "42",
  "event": "call.completed",
  "targetUrl": "https://ornek.com/purvisor/webhook",
  "secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

Geçersiz gövde (örn. http:// URL veya tanınmayan olay) → HTTP 400 {"error":"validation_error","details":[...]}.

Abonelikleri listele — GET /api/v1/hooks

Hesabınızın tüm aktif ve pasif aboneliklerini döndürür. Secret asla listede yer almaz.

curl https://app.purvisor.ai/api/v1/hooks \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "id": "42",
      "event": "call.completed",
      "targetUrl": "https://ornek.com/purvisor/webhook",
      "source": "custom",
      "isActive": true,
      "failCount": 0,
      "lastDeliveryAt": "2026-07-12T09:14:03.000Z",
      "createdAt": "2026-07-10T11:02:55.000Z"
    }
  ]
}

Aboneliği kaldır — DELETE /api/v1/hooks/{id}

Zapier/Make bunu Zap kapatıldığında otomatik çağırır.

curl -X DELETE https://app.purvisor.ai/api/v1/hooks/42 \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Başarılı yanıt → {"success": true}

Örnek payload’lar — GET /api/v1/samples

Zapier/Make, Zap kurulumunda alan eşleştirme ekranını çizebilmek için gerçekçi bir örnek payload’a ihtiyaç duyar. Bu uç, istenen olay için statik, sabit bir örnek döndürür — canlı kiracı verisi sızdırmaz.

curl "https://app.purvisor.ai/api/v1/samples?event=call.completed" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "callId": "9f3c2a1e-7b4d-4e8a-b2c5-1d6f8a9e0b3c",
      "phoneNumber": "+905321234567",
      "direction": "outbound",
      "durationSeconds": 184,
      "outcome": "interested",
      "sentiment": "positive",
      "summary": "Ahmet Bey ürünle ilgilendi, fiyat bilgisi istedi. Salı günü saat 14:00 için takip araması planlandı.",
      "contactId": "1042"
    }
  ]
}

event parametresi zorunludur ve 9 olaydan biri olmalıdır; aksi halde HTTP 400 {"error":"invalid_event","validEvents":[...]}. Her olayın alan seti farklıdır.

Webhook olayları

Abonelik oluştururken event için kullanabileceğiniz 6 ad şunlardır:

Teslimat zarfı

Purvisor sizin targetUrl’inize her zaman şu şekilde bir gövde POST eder:

{
  "id": "call.completed:9f3c2a1e-7b4d-4e8a-b2c5-1d6f8a9e0b3c",
  "event": "call.completed",
  "timestamp": "2026-07-12T09:14:03.128Z",
  "data": { }
}

id, olayın deterministik kimliğidir: <olay adı>:<varlığın doğal anahtarı> biçimindedir ve aynı varlık için olay tekrar yayınlanırsa aynı değeri alır. Tüketici tarafında mükerrer işlemi elemek için bu alanı kullanın.

data içeriği olaya göre değişir (yukarıdaki örnek payload’lar gerçek data bloğudur). Teslimat ayrıca şu başlıkları taşır:

Purvisor bir teslimatı 5 kez dener (üstel geri çekilme, 15 sn taban, istek başına 10 sn zaman aşımı). 2xx dışı her yanıt yeniden denenir; 10 ardışık başarısızlık sonrası abonelik otomatik isActive=false yapılır. Başarılı teslimat failCount’u sıfırlar.

KVKK notu: Webhook payload’ları telefon numarası, ad-soyad ve görüşme özeti gibi kişisel veri taşır. targetUrl her zaman https:// olmak zorundadır (Purvisor http:// kabul etmez), ancak alıcı uçta da bu veriyi güvenli saklamak, erişimi sınırlamak ve saklama sürelerini KVKK’ya uygun yönetmek sizin sorumluluğunuzdadır.

Sorun giderme

İlgili