Webhook Entegrasyonu (Paraşüt, CRM, Slack)

Webhook, GalagoAI'de bir olay gerçekleştiğinde belirlediğiniz URL'e otomatik HTTP POST isteği gönderen mekanizmadır. Çağrı bittiğinde CRM'inizi güncelleyebilir, faturalandırmayı Paraşüt'e aktarabilir, kritik alarmı Slack'e düşürebilirsiniz.

Desteklenen Olay Tipleri

• call.started — Çağrı başladığında
• call.ended — Çağrı kapandığında
• call.transcript.ready — Transkript üretildiğinde
• sentiment.alarm — Sentiment alarmı tetiklendiğinde
• operator.added — Yeni operatör eklendiğinde
• invoice.created — Fatura kesildiğinde
• plan.changed — Plan değiştirildiğinde

Adım 1 — Webhook URL'i Tanımlama

Panel > Entegrasyonlar > Webhook'lar > Yeni Webhook. Doldurulacak alanlar: adı (örn. 'Slack Sentiment Alarmı'), URL (HTTPS zorunlu), olaylar (hangi olaylarda tetiklenecek), gizli anahtar (imza doğrulaması için, otomatik üretilir), yeniden deneme.

Adım 2 — Hazır Şablonlar

Paraşüt Faturalandırma: GalagoAI faturası otomatik Paraşüt cari hesaba aktarılır. Olay: invoice.created. Hedef: Paraşüt API endpoint'i.

Slack Bildirimi: channel + username + text alanlı JSON payload. HubSpot CRM: call.ended olayında caller ID ile lead eşle, çağrı aktivitesi kaydet, transkript ek dosya olarak yükle. Pipedrive CRM: HubSpot'a benzer akış; Activities endpoint'i kullanılır.

Adım 3 — Payload Yapısı

Tüm webhook'lar JSON formatında POST edilir. Örnek call.ended payload:

{
  "event": "call.ended",
  "tenant_id": "lf-2026",
  "timestamp": "2026-05-13T14:23:15Z",
  "call": {
    "id": "uuid-v4",
    "fusionpbx_uuid": "abc-123",
    "direction": "inbound",
    "from": "+905323334455",
    "to": "+903244333334",
    "operator": { "name": "Şebnem Güngör", "extension": "1042" },
    "duration_seconds": 247,
    "sentiment_avg": 0.42,
    "recording_url": "https://galagoai.com/r/abc-123.mp3"
  }
}

Adım 4 — İmza Doğrulama (Güvenlik)

Her POST isteği X-Galago-Signature başlığı taşır. Bu HMAC-SHA256 imzayı doğrularsanız sahte istekleri reddedebilirsiniz.

// Node.js
const crypto = require('crypto');
const secret = process.env.WEBHOOK_SECRET;

function verifySignature(rawBody, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return expected === signature;
}

# Python
import hmac, hashlib, os

secret = os.environ['WEBHOOK_SECRET'].encode()

def verify_signature(raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Adım 5 — Yeniden Deneme Politikası

Hedef URL 2xx yanıt vermezse: 1. tekrar 30 sn sonra, 2. tekrar 2 dk, 3. tekrar 10 dk, 4. tekrar 1 saat, 5. tekrar 6 saat. 5. denemede de başarısızsa webhook pasif işaretlenir, panel bildirimi gönderilir.

Adım 6 — Test Aracı

Panel > Entegrasyonlar > Webhook > Test butonuyla seçili olayın örnek payload'ı kendi URL'inize gönderilir. Hedef sisteminizde log'u görüp doğrulayabilirsiniz.

Hata Kodlarının Anlamı

• 401 — İmza doğrulama hatası. Çözüm: Secret değerini kontrol edin
• 404 — Endpoint bulunamadı. Çözüm: URL'i panel'de güncelleyin
• 429 — Rate limit. Çözüm: hedef sistemi ölçeklendirin
• 5xx — Hedef sunucu hatası. Çözüm: hedef sistemde log kontrolü

IP Whitelist

GalagoAI sunucu IP listesi: 185.121.126.19/32. Hedef sisteminizde firewall whitelist'ine bu IP eklenir.