Olay Bildirim Sistemi (Outbound Webhooks)

Webhooks & Canlı Olay Dinleme

GelsinSatışlar Webhook mekanizması, gelen yeni bir WhatsApp mesajı veya iletim durumu değişikliği olduğunda sunucunuza anlık (real-time) HTTP POST bildirimi gönderir.

Hiç Bilmeyenler İçin Basitçe Anlatım

Webhook Nedir? (Kapı Zili Örneğiyle)

Kapınızda bir kapı zili olduğunu düşünün. Misafir geldiğinde sizin sürekli kapıya bakmanız gerekmez. Misafir zile basar, siz duyarsınız ve kapıyı açarsınız. Webhook tam olarak budur.

Normalde programlar birbirine "bir şey oldu mu?" diye sürekli sorar (buna polling denir). Webhook'ta ise GelsinSatışlar size önceden verdiğiniz adrese olay olur olmaz kendisi haber verir: "Yeni mesaj geldi!" diye zili çalar. Sizin sormanıza gerek kalmaz.

ÖzetAPI "ben istediğimde alırım" sistemidir; webhook ise "olay olunca bana gelsin" sistemidir. Webhook, anlık (gerçek zamanlı) bildirim almanın en verimli yoludur.

POSThttps://gelsinsatislar.com/api/v1/webhooksScope: webhooks:manage

1. Webhook Adresi Kaydetme

Sunucunuzun HTTPS adresini ve dinlemek istediğiniz olay listesini ileterek webhook kaydınızı oluşturun:

curl -X POST "https://gelsinsatislar.com/api/v1/webhooks" \
  -H "Authorization: Bearer gelsinsatislar_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.siteniz.com/webhooks/whatsapp",
    "events": ["message.received", "message.status_updated"]
  }'

{
  "data": {
    "id": "wh_994821a",
    "url": "https://api.siteniz.com/webhooks/whatsapp",
    "events": ["message.received", "message.status_updated"],
    "secret": "whsec_38f2a1b9c8d7e6f5a4b3c2d1e0f9a8b7",
    "created_at": "2026-08-08T22:00:00Z"
  },
  "error": null
}

Önemli: secret değeri yalnızca kayıt esnasında bir kez açık şekilde döndürülür. Gelen isteklerin imzasını doğrulamak için bu gizli anahtarı saklayın.

2. HMAC SHA-256 İmza Doğrulama (Security)

GelsinSatışlar sunucunuza her webhook gönderdiğinde X-Gelsinsatislar-Signature başlığını iletir. Sahte (Spoofing) istekleri engellemek için gelen ham gövdeyi (Raw Body) imzalayarak doğrulayın:

Basitçe Anlatım

İmza doğrulama, gelen paketin gerçekten GelsinSatışlar'dan mı geldiğini anlamanın yoludur. Kapı ziliyle gelen kişinin gerçekten tanıdığınız biri olup olmadığını kapı deliğinden kontrol etmek gibidir. GelsinSatışlar her bildirimin yanına gizli anahtarınızla (secret) çizilmiş bir "mühür" (imza) koyar. Siz bu mührü aynı anahtarla kontrol edersiniz. Mühür tutarsa bildirim gerçektir. Tutmazsa sahtedir ve reddedilir.

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

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

3. Olay Kataloğu (Event Payloads)

A. Gelen Mesaj Olayı (`message.received`)

{
  "event": "message.received",
  "timestamp": "2026-08-08T22:15:00Z",
  "data": {
    "message_id": "msg_991823",
    "conversation_id": "conv_12345",
    "from": "+905320000000",
    "contact_name": "Ahmet Yılmaz",
    "type": "text",
    "text": "Sipariş durumum nedir?"
  }
}