Webhooks & Gerçek Zamanlı Olay Dinleme
GelsinSatışlar Webhook mekanizması, yeni bir WhatsApp mesajı alındığında veya iletim durumu değiştiğinde sunucunuza anlık (real-time) HTTP POST bildirimi gönderir. Bu sayede polling ihtiyacını ortadan kaldırarak entegrasyonlarınızı verimli hale getirirsiniz.
gelsinsatislar_test_ önekli bir anahtarla gönderdiğinizde hiçbir kayıt oluşmaz veya değişmez; kayıt yanıtındaki imza anahtarı da yalnızca test amaçlıdır. Ayrıntılar: anahtar türleri ve kısıtlamalar.1. Webhook Adresi Kaydetme
Sunucunuzun HTTPS adresini ve dinlemek istediğiniz olay listesini belirterek webhook kaydınızı oluşturun. url değeri mutlaka https:// ile başlamalıdır. Kayıt başarısız olduğunda endpoint otomatik olarak devre dışı bırakılır.
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
}secret değeri yalnızca kayıt esnasında bir kez açık şekilde döndürülür. Gelen isteklerin HMAC imzasını doğrulamak için bu değeri güvenli bir şekilde saklayın.1b. Webhook Yönetim Uç Noktaları
Kayıtlı webhook uç noktalarınızı yönetmek için aşağıdaki uç noktaları kullanın. Tüm işlemler webhooks:manage kapsamı gerektirir.
| Yöntem | Uç Nokta | Açıklama |
|---|---|---|
| GET | /api/v1/webhooks | Tüm webhook uç noktalarını listeler (secret değeri dahil edilmez). |
| GET | /api/v1/webhooks/{id} | Belirli bir webhook uç noktasının detaylarını getirir. |
| PATCH | /api/v1/webhooks/{id} | url, events veya is_active alanlarını günceller. Yeniden etkinleştirme hata sayacını sıfırlar. |
| DELETE | /api/v1/webhooks/{id} | Webhook uç noktasını kalıcı olarak siler. |
curl -X GET "https://gelsinsatislar.com/api/v1/webhooks" \
-H "Authorization: Bearer gelsinsatislar_live_YOUR_API_KEY"2. HMAC SHA-256 İmza Doğrulama (Security)
GelsinSatışlar sunucunuza her webhook gönderdiğinde X-Gelsinsatislar-Signature başlığını ekler. Sahte istekleri (spoofing) engellemek için gelen HTTP gövdesini (raw body) HMAC SHA-256 algoritmasıyla imzalayarak doğrulayın.
İmza formatı: X-Gelsinsatislar-Signature: t=<unix_seconds>,v1=<hex> şeklindedir. t Unix zaman damgası, v1 ise HMAC-SHA256 sonucudur. Aşağıdaki HTTP başlıkları da her webhook isteğiyle birlikte iletilir:
| Başlık | Açıklama |
|---|---|
| X-Gelsinsatislar-Event | Tetiklenen olay türü (ör: message.received). |
| X-Gelsinsatislar-Webhook-Id | Webhook uç noktanızın benzersiz tanımlayıcısı. |
| X-Gelsinsatislar-Signature | t/v1 formatında HMAC-SHA256 imzası. |
const crypto = require('crypto');
function verifyWebhook(rawBody, signatureHeader, secret) {
// Imza formati: t=<unix_seconds>,v1=<hex>
const match = signatureHeader.match(/t=(\d+),v1=([0-9a-f]+)/);
if (!match) return false;
const [, t, v1] = match;
const expectedV1 = crypto
.createHmac('sha256', secret)
.update(t + '.' + rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(v1),
Buffer.from(expectedV1)
);
}3. Teslim Zarfı (Delivery Envelope)
Her webhook teslimatı aşağıdaki standart JSON zarfı (envelope) formatında gönderilir. id alanı benzersiz bir UUID olup tekrar teslimleri (deduplication) önlemek için kullanılır. data alanı olay türüne göre değişir.
{
"id": "8f3c2a19-9482-4b21-a123-bc4d5e6f7a8b",
"event": "message.received",
"occurred_at": "2026-08-08T22:15:00.000Z",
"account_id": "acc_99481230",
"data": {
// Olay türüne göre değişen alanlar — aşağıdaki bölüme bakın
}
}4. Olay Kataloğu (Event Payloads)
Desteklenen tüm olay türleri ve data alanları aşağıdadır. Bir webhook uç noktası yalnızca abone olduğu olayları alır.
| Olay | Tetiklenme Koşulu |
|---|---|
| message.received | Bir müşteri tarafından yeni bir gelen mesaj alındığında tetiklenir. |
| message.status_updated | Gönderilen bir mesajın iletim durumu değiştiğinde tetiklenir (sent → delivered → read). |
| conversation.created | Bir müşteri ile yeni bir sohbet başlığı açıldığında tetiklenir. |
| lead.created | A sales-pipeline lead card was created data: lead_id, pipeline_id, stage_id, contact_id, conversation_id, value, currency, status |
| lead.stage_changed | A sales-pipeline lead changed stage data: lead_id, pipeline_id, stage_id, previous_stage_id, contact_id, conversation_id, value, currency, status |
| order.created | An integration order was linked to a lead data: provider, external_order_id, lead_id |
| payment.completed | A verified payment callback marked a link paid data: payment_link_id, provider, contact_id, lead_id, amount, currency, paid_at |
| handoff.requested | The AI or a conversation flow requested a human handoff data: conversation_id, contact_id, assigned_agent_id |
| conversation.closed | A conversation was closed data: conversation_id, contact_id, assigned_agent_id |
Lead olayları satış panosundaki kartları kapsar; randevu/rezervasyon kartlarını veya platformun pazarlama formlarını kapsamaz. Sipariş olayı, entegrasyonun siparişi ilk kez bir karta eşleştirmesidir. Ödeme olayı doğrulanmış sağlayıcı bildiriminin kayıtlı ödeme linkini ilk kez ödendi durumuna geçirmesidir; doğrudan durum düzenlemesi değildir. İnsan devri olayı AI devir özetiyle birlikte durdurulduğunda veya bir sohbet akışı temsilciye devredildiğinde oluşur; yalnızca manuel duraklatma olay üretmez. 112/113 migration dosyalarıyla iş ve mesaj olayları kaynak kayıtla aynı transaction içinde kuyruğa alınır. Uygulama teslimi hızlandırır; kesilen teslim çağrısını zamanlayıcı kurtarır. Teslim sırası ve alıcıda tek seferlik etki garantisi verilmez.
A. Gelen Mesaj Olayı (message.received)
Bir müşteri tarafından gönderilen yeni bir WhatsApp mesajı alındığında tetiklenir. data alanı mesajın içeriği ve ilgili sohbet/müşteri bilgilerini içerir.
{
"id": "8f3c2a19-9482-4b21-a123-bc4d5e6f7a8b",
"event": "message.received",
"occurred_at": "2026-08-08T22:15:00.000Z",
"account_id": "acc_99481230",
"data": {
"conversation_id": "conv_12345",
"contact_id": "cnt_10294",
"whatsapp_message_id": "wamid.HBgLOTE1NTE1NTE1NQ==",
"content_type": "text",
"text": "Sipariş durumum nedir?"
}
}| Alan | Tipi | Açıklama |
|---|---|---|
| conversation_id | string | Mesajın ait olduğu sohbetin benzersiz tanımlayıcısı. |
| contact_id | string | Mesajı gönderen müşterinin benzersiz tanımlayıcısı. |
| whatsapp_message_id | string | Meta tarafından atanan WhatsApp mesaj tanımlayıcısı. |
| content_type | string | Mesaj içeriği türü: text, image, video, audio, document, interactive. |
| text | string | Mesajın metin içeriği (metin mesajlarında zorunlu). |
B. Mesaj Durum Güncellemesi (message.status_updated)
Gönderilen bir mesajın iletim durumu değiştiğinde tetiklenir. Bu olay, API tarafından gönderilen ve gelen kutusundan iletilen mesajları kapsar. Aynı durum birden fazla kez veya sırasız olarak gelebilir; id alanı ile tekrar kontrolü yapmanız önerilir.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event": "message.status_updated",
"occurred_at": "2026-08-08T22:16:30.000Z",
"account_id": "acc_99481230",
"data": {
"whatsapp_message_id": "wamid.HBgLOTE1NTE1NTE1NQ==",
"conversation_id": "conv_12345",
"status": "delivered"
}
}| Alan | Tipi | Açıklama |
|---|---|---|
| whatsapp_message_id | string | Durumu değişen mesajın WhatsApp tanımlayıcısı. |
| conversation_id | string | Mesajın ait olduğu sohbetin tanımlayıcısı. |
| status | string | Yeni iletim durumu. |
Desteklenen status Değerleri
| sent | Mesaj Meta tarafından alındı ve gönderim kuyruğuna eklendi. |
| delivered | Mesaj alıcının cihazına başarıyla iletildi. |
| read | Alıcı mesajı okudu (mavi onay işareti). |
| failed | Mesaj iletilemedi (hata detayı için API yanıtına bakın). |
C. Yeni Sohbet Oluşturuldu (conversation.created)
Bir müşteri ile yeni bir sohbet başlığı açıldığında tetiklenir. Genellikle ilk gelen mesaj ile birlikte oluşur.
{
"id": "c4d5e6f7-a8b9-0123-cdef-456789abcdef",
"event": "conversation.created",
"occurred_at": "2026-08-08T22:15:00.000Z",
"account_id": "acc_99481230",
"data": {
"conversation_id": "conv_12345",
"contact_id": "cnt_10294"
}
}| Alan | Tipi | Açıklama |
|---|---|---|
| conversation_id | string | Yeni oluşturulan sohbetin benzersiz tanımlayıcısı. |
| contact_id | string | Sohbete ait müşterinin benzersiz tanımlayıcısı. |
5. Teslim Semantikleri (Delivery Semantics)
Webhook teslimatları aşağıdaki kurallara tabidir. Entegrasyonunuzu tasarlarken bu davranışları hesaba katmanız önerilir.
Kalıcı Kuyruk ve Yeniden Deneme
Migration 110 ve zamanlayıcı etkin olduğunda kuyruğa alınan olaylar ilk denemeden sonra 1, 2, 4, 8 ve 16 dakika aralıklarla beş kez yeniden denenir. Yönlendirmeler takip edilmez. Denemeleri tükenen kayıtlar ayarlardaki başarısız teslimlerden tekrar kuyruğa alınabilir.
Tekrar Tespit (Deduplication)
Meta sağlayıcıları durum güncellemelerini birden fazla kez veya sırasız gönderebilir. Aynı olay id alanı ile birden fazla kez gelebilir; teslim zarfındaki benzersiz id ile tekrar kontrolü yapın.
Otomatik Devre Dışı Bırakma
Ardışık başarısız teslimatlar sayaç mantığıyla takip edilir. Eşik değerine ulaşıldığında (15 ardışık hata) endpoint otomatik olarak devre dışı bırakılır (is_active: false). PATCH ile yeniden etkinleştirme hata sayacını sıfırlar.
SSRF Koruması
Webhook URL'i yalnızca herkese açık HTTPS adreslerine yönlendirilebilir. localhost, RFC1918 (özel) aralıklar, link-local ve bulut meta adresleri hedeflenemez. Uyumsuz URL'ler başarısız teslimat olarak sayılır.