Webhooks

DOLU.ai olaylarini harici sistemlere bildirmek icin webhook'lar kullanin.

Genel Bakis

Webhook'lar, DOLU.ai'de bir olay gerceklestiginde belirlediginiz URL'ye HTTP POST istegi gonderir.

Webhook Olusturma

Arayuzden

1. Ayarlar > Webhooks'a gidin
2. Yeni Webhook butonuna tiklayin
3. URL girin
4. Olaylari secin
5. Kaydedin

API ile

POST /api/v1/webhooks

{
  "url": "https://your-server.com/webhook",
  "events": [
    "message.received",
    "conversation.created",
    "contact.created"
  ],
  "secret": "your_webhook_secret"
}

Desteklenen Olaylar

Mesaj Olaylari

Olay	Aciklama
message.received	Yeni mesaj geldi
message.sent	Mesaj gonderildi
message.delivered	Mesaj teslim edildi
message.read	Mesaj okundu
message.failed	Mesaj basarisiz

Konusma Olaylari

Olay	Aciklama
conversation.created	Yeni konusma basladi
conversation.updated	Konusma guncellendi
conversation.assigned	Konusma atandi
conversation.closed	Konusma kapandi

Kisi Olaylari

Olay	Aciklama
contact.created	Yeni kisi eklendi
contact.updated	Kisi guncellendi
contact.deleted	Kisi silindi

Firsat Olaylari

Olay	Aciklama
deal.created	Yeni firsat
deal.updated	Firsat guncellendi
deal.stage_changed	Asama degisti
deal.won	Kazanildi
deal.lost	Kaybedildi

Gorev Olaylari

Olay	Aciklama
task.created	Yeni gorev
task.completed	Tamamlandi
task.overdue	Gecikti

Payload Formati

Genel Yapi

{
  "id": "evt_abc123xyz",
  "event": "message.received",
  "timestamp": "2024-01-21T10:30:00Z",
  "data": {
    ...
  }
}

Ornek: Mesaj Geldi

{
  "id": "evt_msg123",
  "event": "message.received",
  "timestamp": "2024-01-21T10:30:00Z",
  "data": {
    "messageId": "msg_abc123",
    "conversationId": "conv_xyz789",
    "contactId": "contact_456",
    "channel": "whatsapp",
    "text": "Merhaba, bilgi alabilir miyim?",
    "direction": "incoming",
    "sender": {
      "id": "contact_456",
      "name": "Ahmet Yilmaz",
      "phone": "+905551234567"
    }
  }
}

Ornek: Konusma Olusturuldu

{
  "id": "evt_conv123",
  "event": "conversation.created",
  "timestamp": "2024-01-21T10:30:00Z",
  "data": {
    "conversationId": "conv_xyz789",
    "contactId": "contact_456",
    "channel": "whatsapp",
    "source": "organic",
    "contact": {
      "id": "contact_456",
      "firstName": "Ahmet",
      "lastName": "Yilmaz",
      "phone": "+905551234567"
    }
  }
}

Guvenlik

Imza Dogrulama

Her webhook istegi X-Dolu-Signature header'i icerir:

X-Dolu-Signature: sha256=abc123def456...

Imza Kontrolu

const crypto = require('crypto');

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

  return signature === `sha256=${expectedSignature}`;
}

// Express middleware
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-dolu-signature'];
  const payload = JSON.stringify(req.body);

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

  // Process webhook
  console.log('Event:', req.body.event);
  res.status(200).send('OK');
});

Python Ornegi

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return signature == f'sha256={expected}'

Yeniden Deneme

Basarisiz webhook'lar yeniden denenir:

Deneme	Bekleme
1	1 dakika
2	5 dakika
3	30 dakika
4	2 saat
5	24 saat

5 denemeden sonra webhook devre disi birakilir.

Basari Kriterleri

Webhook basarili sayilir eger:

• HTTP 2xx yaniti alinirsa
• Yanit 30 saniye icinde gelirse

Webhook Yonetimi

Listeleme

GET /api/v1/webhooks

Guncelleme

PUT /api/v1/webhooks/:id

Silme

DELETE /api/v1/webhooks/:id

Devre Disi Birakma

POST /api/v1/webhooks/:id/disable

Aktif Etme

POST /api/v1/webhooks/:id/enable

Test Etme

Test Istegi Gonderme

POST /api/v1/webhooks/:id/test

{
  "event": "message.received"
}

Webhook Loglari

GET /api/v1/webhooks/:id/logs

En Iyi Uygulamalar

1. Hizli yanit verin: 5 saniye icinde 200 donun
2. Asenkron isleyin: Agir isleri kuyruge alin
3. Idempotent olun: Ayni olayı birden fazla kez isleyebilmelisiniz
4. Imzayi dogrulayin: Guvenlik icin sart
5. Loglayın: Gelen webhook'lari kaydedin
6. Hata yonetimi: Hatalari yakalayin ve loglayın