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.
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. |
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.
En Fazla Bir Kez Teslim (Best-Effort)
Her olay için tek bir deneme yapılır ve kısa bir zaman aşımı uygulanır. Yönlendirmeler (redirects) takip edilmez. Başarısız teslimatlarda yeniden deneme (retry) yapılmaz.
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.
GET /messages) karşılaştırmanız önerilir.