Webhook Nedir? API'den Farkı, Nasıl Çalışır ve Gerçek Örneklerle Kurulum

Webhook, bir sistemde olay gerçekleştiği anda başka bir sisteme HTTP POST isteği gönderilmesidir. Türkçesi web kancası. Siz sormazsınız, olay size gelir: ödeme alındığında, sipariş oluştuğunda ya da yeni kişi CRM'e düştüğünde belirlediğiniz adrese JSON gövdeli imzalı bir istek düşer ve sunucunuz 2xx döner.

Bu yazı tanımda durmuyor. Gerçek bir istek gövdesini, başlıklarıyla birlikte açıyoruz; imzayı Node.js ve Python ile doğruluyoruz; alıcı sunucu yazmadan webhook almanın kodsuz yollarını (n8n, Make, Zapier) adım adım kuruyoruz; teslimat başarısız olduğunda ne olduğunu, kaç kez denendiğini ve aynı olayı iki kez işlememek için ne yapmanız gerektiğini anlatıyoruz. Sonunda bir CRM örneği var: fırsat kazanıldığında tablonuza satır eklenmesi ve ekip kanalına bildirim düşmesi, tek satır kod yazmadan.

Teoriyi atlamak isterseniz, Pinlyx webhook sayfası hangi olayların yayımlandığını, imzanın hangi başlıkla geldiğini ve teslimat kaydının neye benzediğini tek ekranda gösteriyor.

Webhook nedir: kapı zili benzetmesi ve neden "web kancası" deniyor

Bir sistemin başka bir sisteme "şu oldu" demesinin iki yolu vardır. Birincisi, sürekli sorup öğrenmek. İkincisi, olduğu anda haber almak. Webhook ikincisidir.

Günlük hayattan karşılığı şu: kapınızın önünde birinin olup olmadığını anlamak için her beş dakikada bir kapıyı açıp bakabilirsiniz. Çoğu sefer kimse yoktur, boşuna kalkmış olursunuz; birisi geldiğinde de en kötü ihtimalle beş dakika bekletirsiniz. Ya da kapıya bir zil takarsınız. Zil çaldığında kalkarsınız, çalmadığında oturmaya devam edersiniz. Webhook, yazılım dünyasındaki zildir. Zilin kablosu sizin adresinizdir, yani bir URL; zile basan taraf ise olayın gerçekleştiği sistemdir.

Terimin "kanca" kısmı buradan geliyor. Bir sisteme kanca atarsınız, o sistem kendi akışının belirli bir noktasına geldiğinde kancayı çeker ve sizin kodunuz çalışır. Yazılımcılıkta "hook" kelimesi uzun zamandır bir programın içine dışarıdan kod iliştirmek anlamında kullanılıyordu; webhook, bunun HTTP üzerinden ve ağ boyunca yapılan hâli. Türkçe kaynaklarda "web kancası" karşılığını görürsünüz, ama sektörde konuşma dili webhook olarak kaldı. İki terim de aynı şeyi anlatır.

Teknik tanım, tek cümlede

Webhook, bir olay gerçekleştiğinde kaynak sistemin, alıcının önceden kaydettiği bir HTTP adresine, olayın ayrıntılarını gövdesinde taşıyan bir POST isteği göndermesidir.

Bu cümledeki her kelime bir tasarım kararı içeriyor:

• Olay gerçekleştiğinde: zamanlama olayın kendisine bağlıdır, saat başına ya da zamanlanmış göreve değil. Gecikme genelde bir saniyenin altındadır.
• Kaynak sistem gönderir: istemci rolü tersine döner. Normal API kullanımında siz istek atarsınız; webhookta size istek atılır. Bu yüzden alıcı tarafın internete açık bir adresi olması gerekir.
• Önceden kaydettiği adres: webhook kendiliğinden başlamaz. Bir yere gidip adresinizi yazarsınız, hangi olayları istediğinizi seçersiniz. Kayıt yoksa teslimat da yoktur.
• POST isteği: neredeyse her zaman POST ve neredeyse her zaman JSON. Bazı eski sistemler form verisi (application/x-www-form-urlencoded) gönderir; Slack ve Discord'un gelen webhookları gibi bazıları da JSON bekler ama şemayı kendileri dayatır.
• Gövdesinde taşıyan: olayın verisi istek gövdesindedir. Bazı sistemler yalnızca "şu kaydın kimliği değişti" der ve ayrıntıyı API'den çekmenizi bekler; bazıları kaydın tamamını gönderir. İkisinin de gerekçesi vardır, aşağıda ayrıca ele alıyoruz.

Webhook, API ve entegrasyon aynı şey değil

Üç kelime sık sık birbirinin yerine kullanılıyor ve bu, kurulum sırasında kafa karışıklığının en büyük kaynağı.

API, bir sistemin dışarıya açtığı arayüzün tamamıdır. Webhook da bu arayüzün bir parçasıdır, ama tersine çalışan parçası. Bir ürünün "REST API'si var" demesi genelde "siz ona istek atabilirsiniz" demektir; "webhook'u var" demesi ise "o size istek atabilir" demektir. Olgun ürünlerin ikisi de vardır ve bunlar birbirini tamamlar: webhook size bir şeyin olduğunu söyler, API o şeyin ayrıntısını okumanızı ya da değiştirmenizi sağlar.

Entegrasyon, iki sistemin birlikte çalışmasının genel adıdır. Webhook bir entegrasyon tekniğidir, entegrasyonun kendisi değil. Aynı işi dosya aktarımıyla, veritabanı kopyalamayla, zamanlanmış API çağrılarıyla ya da mesaj kuyruklarıyla da yapabilirsiniz. Webhook'un öne çıkmasının nedeni, kurulumunun ucuz olması: bir URL, bir gizli anahtar ve bir HTTP uç noktası yeterlidir.

Hangi araçların birbirine bağlanabileceğini merak ediyorsanız entegrasyonlar sayfası Pinlyx tarafındaki hazır bağlantıları listeler; webhook, o listede karşılığı olmayan her sistem için genel çözümdür.

Webhook API farkı: yoklama mı, itme mi

"Webhook api farkı" sorusunun kısa cevabı, yönün ters olmasıdır. Uzun cevabı, bu yön farkının maliyet, gecikme ve hata davranışı üzerinde yarattığı sonuçlardır.

Klasik yol yoklamadır (polling): kodunuz belirli aralıklarla API'ye sorar, "yeni bir şey var mı" der, gelen listeyi kendi kaydıyla karşılaştırır. Beş dakikada bir soran bir görev, günde 288 istek atar. Bu isteklerin ezici çoğunluğu boş döner. Üstelik bir şey olduğunda bile ortalama iki buçuk dakika geç öğrenirsiniz.

İtme (push) yolu webhooktur: bir şey olduğunda tek bir istek gelir. Hiçbir şey olmadığında hiçbir istek gelmez. Gecikme, kaynak sistemin kuyruğunun uzunluğu kadardır, genelde saniyenin altında.

Hangisini ne zaman seçmeli

Karar aslında üç soruya bakar.

Gecikme sizin için önemli mi? Bir ödeme onayının sipariş ekranına yansıması saniyeler içinde olmalıysa webhook şart. Gece çalışan bir muhasebe mutabakatı için beş dakikalık gecikmenin anlamı yoktur, yoklama yeterlidir.

Alıcı tarafta açık bir adres barındırabiliyor musunuz? Webhook, sizin tarafınızda 7/24 ayakta duran, sertifikası geçerli, herkese açık bir HTTPS ucu ister. Şirket içi ağda kapalı duran bir uygulama için bu kolay değildir. Böyle durumlarda ya kodsuz bir aracı (n8n, Make, Zapier) araya koyarsınız ya da yoklamada kalırsınız.

Tamlık mı, hız mı? Webhook hızlıdır ama kaçırma ihtimali sıfır değildir: uç noktanız uzun süre kapalı kalırsa gönderen taraf bir noktada pes eder. Finansal mutabakat gibi tek bir kaydı bile kaçıramayacağınız işlerde doğru desen ikisini birden kullanmaktır. Webhook anlık tepkiyi verir, günde bir çalışan bir yoklama işi de "kaçan var mı" diye bakar. Stripe'ın kendi belgeleri bile teslimatın sırasının garanti edilmediğini ve olayların kimliğine göre tekilleştirilmesi gerektiğini yazıyor (docs.stripe.com/webhooks, Eylül 2026'da kontrol edildi).

"Sadece kimlik gönder" ile "her şeyi gönder" arasındaki tercih

Webhook gövdesinde ne kadar veri olacağı, sağlayıcının aldığı bir karardır ve ikisinin de mantığı vardır.

İnce zarf yalnızca olayın türünü ve ilgili kaydın kimliğini taşır. Alıcı, ayrıntıyı API'den çeker. Avantajı, verinin her zaman güncel olmasıdır: iki saniye arayla iki değişiklik olduysa siz en son hâli okursunuz. Dezavantajı, her webhook için bir API çağrısı daha yapmanız ve kota harcamanızdır.

Kalın zarf kaydın anlamlı alanlarını gövdeye koyar. Avantajı, çoğu işin tek istekle bitmesidir. Dezavantajı, zarf içindeki verinin gönderildiği andaki fotoğraf olmasıdır; arada bir şey değiştiyse elinizdeki eski olabilir.

Pinlyx kalın zarfı seçiyor ve her olayın kendi alanlarını gönderiyor; ayrıntıyı değiştirmek istediğinizde genel REST API aynı kayda erişim verir. Yani okumak için ikinci bir istek şart değil, yazmak için API oradadır.

Webhook nasıl çalışır: olaydan 2xx yanıtına altı adım

"Webhook nasıl çalışır" sorusunun cevabı altı adımda biter. Aşağıdaki akış, hangi sağlayıcıyla çalışırsanız çalışın aynıdır; değişen yalnızca başlık adları ve zarf biçimidir.

1. Kayıt. Kaynak sistemin panelinde bir uç nokta oluşturursunuz: HTTPS adresi, ilgilendiğiniz olaylar ve size bir kez gösterilen bir gizli anahtar.
2. Olay. Kaynak sistemde bir şey olur: fırsat kazanılır, fatura ödenir, kişi eklenir.
3. Kuyruk. Sistem, o olaya abone olan uç noktalar için birer teslimat kaydı oluşturur. İyi tasarlanmış sistemler teslimatı isteğin kendi işlemine bağlamaz; kuyruğa yazar ve arka plandaki bir işçi gönderir. Böylece sizin sunucunuz yavaşsa kaynak sistemdeki kullanıcı beklemez.
4. Gönderim. İşçi, gövdeyi hazırlar, imzayı hesaplar, başlıkları ekler ve POST eder.
5. Doğrulama ve işleme. Siz imzayı kontrol edersiniz, gövdeyi ayrıştırırsınız, işi kuyruğa alırsınız.
6. Yanıt. 2xx dönersiniz ve teslimat başarılı sayılır. 2xx dönmezseniz ya da zaman aşımına uğrarsanız, gönderen taraf yeniden dener.

Gerçek bir istek: başlıklar ve gövde

Aşağıdaki, Pinlyx'in bir fırsat kazanıldığında gönderdiği isteğin tamamıdır. Üstteki satırlar HTTP başlıkları, altındaki JSON ise gövde.

POST /hooks/crm HTTP/1.1
Host: api.sizin-sunucunuz.com
Content-Type: application/json; charset=utf-8
X-Webhook-Event: deal.won
X-Webhook-Event-Id: 7c1f0e5a9b6d4a3e8f2c1d0b9a8e7f6d
X-Webhook-Attempt: 1
X-Webhook-Timestamp: 1789102882
X-Webhook-Signature: sha256=3b1c8f0a... (64 karakterlik onaltılık dize)
User-Agent: Pinlyx-Webhook/1.0

{
  "event": "deal.won",
  "id": "7c1f0e5a9b6d4a3e8f2c1d0b9a8e7f6d",
  "deliveredAt": "2026-09-18T07:41:22.5310000Z",
  "data": {
    "id": 341,
    "userId": 12,
    "actorUserId": 15,
    "title": "Analytical Engines yıllık sözleşme",
    "contactId": 4821,
    "value": 15000,
    "fromStage": "negotiation",
    "closedAt": "2026-09-18T07:41:22Z"
  }
}

Başlıkların her birinin bir işi var:

• X-Webhook-Event: olayın türü. Gövdeyi ayrıştırmadan yönlendirme yapmak istediğinizde işinize yarar.
• X-Webhook-Event-Id: bu teslimatın tekil kimliği. Aynı olay yeniden denendiğinde bu değer değişmez, o yüzden tekrar işlemeyi engellemenin doğru anahtarı budur.
• X-Webhook-Attempt: kaçıncı deneme olduğu. 1 ise ilk gönderim, 3 ise daha önce iki kez başarısız olmuş demektir. Günlüğünüze yazın; sorunun sizde mi olduğunu anlamanın en hızlı yolu.
• X-Webhook-Timestamp: gönderim anının Unix saniyesi. Eski bir isteğin tekrar oynatılmasını engellemek için kullanılır.
• X-Webhook-Signature: sha256= önekiyle, gövdenin gizli anahtarınızla hesaplanmış HMAC-SHA256 özeti. Bir sonraki bölümde tek tek açıyoruz.
• User-Agent: gönderen tarafı tanıtır. Sunucu günlüğünüzde webhook isteklerini ayırmanın en kolay yoludur, ama taklit edilebilir bir değerdir, güvenlik kontrolü olarak kullanmayın.

Gövdedeki zarf da dört alandan oluşuyor: event olayın adı, id teslimatın kimliği, deliveredAt gönderim zamanı ve data olayın kendi verisi. Bu ayrım işinize yarar, çünkü zarfı tek bir yerde ayrıştırıp data kısmını olay türüne göre farklı işleyicilere dağıtabilirsiniz.

Alıcı tarafın yapması gerekenler, sırasıyla

Alıcı uç noktası yazarken sıralama önemlidir ve çoğu hata sıralamadan çıkar.

Önce ham gövdeyi saklayın. İmza, baytların üzerinden hesaplanır. Çerçeveniz gövdeyi JSON'a çevirip sonra tekrar metne döktüyse, boşluklar ve alan sırası değişebilir ve imza tutmaz. Express'te express.raw(), Flask'ta request.get_data(), ASP.NET'te gövdeyi akıştan okumak gerekir.

Sonra imzayı doğrulayın. Gövdeye bakmadan önce. İmzası tutmayan bir istek, içinde ne yazarsa yazsın sizin için gürültüdür.

Sonra hızlıca 2xx dönün. Ağır işi yanıttan önce yapmayın. Yanıt vermeden önce üç tane API çağrısı yapıp veritabanına yazarsanız, yoğun bir anda zaman aşımına uğrarsınız ve gönderen taraf aynı olayı tekrar gönderir. Doğru desen şudur: doğrula, kuyruğa at, 200 dön, işi arka planda yap. Stripe'ın belgeleri de aynı şeyi söylüyor: zaman aşımına yol açabilecek karmaşık mantıktan önce başarılı durum kodunu döndürün (docs.stripe.com/webhooks, Eylül 2026'da kontrol edildi).

En son işleyin. Ve işlerken olay kimliğine bakarak daha önce işlediğiniz bir olayı ikinci kez işlemeyin.

Webhook URL nedir ve nasıl alınır

Webhook URL, teslimatın gideceği adrestir. "Nereden alınır" sorusunun cevabı, hangi tarafta durduğunuza göre değişir ve bu ayrım kafa karıştırıyor.

Gönderen taraftaysanız (yani bir sistemden olay almak istiyorsanız), URL'yi siz üretirsiniz. Kendi sunucunuzdaki bir yol olabilir, bir bulut fonksiyonu olabilir, ya da aşağıdaki kodsuz araçlardan birinin size verdiği adres olabilir. Sonra bu adresi kaynak sistemin paneline yapıştırırsınız.

Alan taraftaysanız (yani bir Discord kanalına ya da Slack kanalına mesaj düşürmek istiyorsanız), URL'yi o platform üretir ve size verir. Discord'un "Copy Webhook URL" düğmesiyle kopyaladığınız adres budur.

1. Kendi sunucunuzda bir uç nokta açmak

En temel yol. Herhangi bir web çerçevesinde bir POST yolu açarsınız, imzayı doğrularsınız, işi yaparsınız. Şartlar kısa:

• Adres internetten erişilebilir olmalı ve HTTPS kullanmalı. Pinlyx, üretimde http:// adresleri ve özel ağ adreslerini reddeder; bir alan adı özel bir IP'ye çözülüyorsa da teslimat yapılmaz. Bu, iç ağınıza istek attırma girişimlerine karşı standart bir önlemdir.
• Uç noktanın kimlik doğrulaması olmamalı, imza doğrulaması olmalı. Webhook göndericisi sizin oturum çerezinizi bilmez; güvenliği imza sağlar.
• Yanıt hızlı dönmeli. Pinlyx her denemede 30 saniye bekler; bu süre içinde yanıt gelmezse deneme başarısız sayılır.

2. Kodsuz alıcılar: n8n, Make, Zapier

Sunucu barındırmak istemiyorsanız, otomasyon araçları size hazır bir webhook adresi verir ve gelen veriyi görsel bir akışta işlemenizi sağlar.

n8n tarafında bunun adı Webhook düğümüdür. Bir tetikleyici düğümdür, yani akışı o başlatır. İki ayrı adres verir: düzenleyicide test yaparken kullandığınız Test URL ve akışı yayına aldığınızda çalışan Production URL. Test adresi yalnızca "Listen for Test Event" dediğinizde dinlemeye geçer ve gelen veriyi ekranda gösterir; üretim adresi ise akış yayımlandığında sürekli çalışır ve gelen veriyi Executions sekmesinden görürsünüz. GET, POST, PUT, PATCH, DELETE ve HEAD yöntemlerini destekler; yanıt biçimi için "Immediately", "When Last Node Finishes", "Using 'Respond to Webhook' Node" ve "Streaming response" seçenekleri vardır; isterseniz Basic auth, Header auth ya da JWT auth ile çağıran tarafı kimlik doğrulamasına tabi tutabilirsiniz (docs.n8n.io, Eylül 2026'da kontrol edildi). n8n'i hiç kullanmadıysanız n8n nedir yazısı kurulumdan fiyat modeline kadar ayrı ayrı anlatıyor.

Make tarafında karşılığı "custom webhooks" modülüdür. Size bir adres verir ve ilk isteği gönderdiğinizde veri yapısını kendisi çıkarır. Bilmeniz gereken sınırlar var: Make, 10 saniyelik pencerede 300 gelen webhook isteğine kadar işler, kuyruk dolduğunda 400, hız sınırında 429 döner ve bir webhook beş gün boyunca hiçbir senaryoya bağlı kalmazsa kendiliğinden devre dışı kalır (help.make.com/webhooks, Eylül 2026'da kontrol edildi).

Zapier tarafında uygulamanın adı "Webhooks by Zapier". Tetikleyici olarak "Catch Hook" gövdeyi ayrıştırarak verir, "Catch Raw Hook" ise ham gövdeyi ve başlıkları 2 MB sınırına kadar olduğu gibi aktarır. Kurulum sırasında Zapier size özel bir adres üretir ve kopyalamanızı ister. Dikkat edilecek nokta: webhook tetikleyicileri Zapier'in ücretsiz planında bulunmaz, ücretli planlarda açılır (help.zapier.com, Eylül 2026'da kontrol edildi). Pinlyx tarafındaki Zapier bağlantısının ayrıntıları için Zapier sayfasına bakabilirsiniz.

3. Test ve ayıklama araçları

Kurulumun ilk yarım saatinde işinizi kolaylaştıran iki araç var.

webhook.site size anında bir adres verir ve oraya gelen her isteği başlıklarıyla, gövdesiyle ve zamanıyla ekranda gösterir. Kendi tanıtımındaki cümle şu: ücretsiz, tekil URL'ler ve e-posta adresleri üretir ve oraya gönderilen her şeyi anında görmenizi sağlar (webhook.site, Eylül 2026'da kontrol edildi). Bir sağlayıcının gerçekte ne gönderdiğini görmek için, kendi kodunuzu yazmadan önce buraya bir test gönderimi yapın. Gövdenin alan adlarını belgeye bakarak tahmin etmekle gerçekten görmek arasında saatler var.

ngrok ise yerel makinenizdeki sunucuyu geçici bir genel adres üzerinden erişilebilir kılar, yani kodunuzu sunucuya çıkmadan gerçek teslimatla deneyebilirsiniz. Ücretsiz bir başlangıç katmanı vardır (ngrok.com, Eylül 2026'da kontrol edildi).

Bir uyarı: bu araçlara giden veriler gerçek müşteri verisi olabilir. Test ederken canlı hesabınızın değil, deneme kaydının olaylarını gönderin.

Gerçek hayattan webhook örnekleri

Webhook'un nerede işe yaradığını görmek, tanımdan daha çok anlatır. Aşağıdakiler yaygın ve ölçülebilir örnekler.

Ödeme sağlayıcısı: ödeme gerçekten alındı mı

Kullanıcı kartını girip "öde" dediğinde tarayıcıda gördüğünüz sonuç, paranın hesabınıza geçtiğinin kanıtı değildir. Kullanıcı ödemeden hemen sonra sekmeyi kapatabilir, banka doğrulaması gecikebilir, üç aşamalı doğrulama yarıda kalabilir. Bu yüzden ödeme sağlayıcıları siparişi tamamlama işini tarayıcıya değil webhook'a bağlamanızı söyler.

Stripe'ın belgeleri bu akışın ayrıntılarını veriyor: imza Stripe-Signature başlığında gelir, içinde t= ile zaman damgası ve v1= ile imza bulunur; resmî kütüphanelerin zaman damgası için varsayılan toleransı 5 dakikadır ve bu tolerans tekrar saldırısına karşı vardır; canlı modda teslimat üç güne kadar üstel bekleme ile yeniden denenir; bir hesap en fazla 16 uç nokta kaydedebilir (docs.stripe.com/webhooks, Eylül 2026'da kontrol edildi). Sayılar sağlayıcıdan sağlayıcıya değişir ama desen aynıdır.

E-ticaret: sipariş oluştu

Mağazanızda sipariş açıldığında depo yazılımının, muhasebenin ve kargo entegrasyonunun haberi olması gerekir. Shopify bunu konu (topic) başına abonelikle yapar; örneğin orders/create konusuna abone olduğunuzda sipariş verisi başlıklarıyla birlikte uç noktanıza gelir ve imza X-Shopify-Hmac-Sha256 başlığında taşınır. Shopify'ın kendi belgesi teslimatın her zaman garanti edilmediğini ve yedek olarak bir mutabakat işi çalıştırmanızı öneriyor (shopify.dev, Eylül 2026'da kontrol edildi). Bu öneri genel bir kuraldır: webhook birincil yol, periyodik kontrol emniyet kemeridir.

CRM: kişi eklendi, fırsat kazanıldı

CRM tarafında webhook'un en çok kullanıldığı iki an var. Birincisi kişinin sisteme girdiği an: yeni bir kayıt oluştuğunda bunu veri ambarınıza, e-posta aracınıza ya da iç panonuza yansıtmak istersiniz. İkincisi fırsatın kazanıldığı an: satış kapandığında fatura oluşturmak, komisyon hesaplamak, müşteriye hoş geldin akışı başlatmak gerekir.

İkinci durumda kritik ayrıntı, olayın yalnızca geçiş anında tetiklenmesidir. Kazanılmış bir fırsat tekrar kaydedildiğinde olay yeniden atılırsa, aşağı akıştaki fatura sistemi ikinci bir fatura keser. Pinlyx bunu deal.won olayını sadece geçişte üreterek çözüyor, ama başka bir sağlayıcıyla çalışıyorsanız bunu belgesinden teyit edin; etmiyorsa idempotency sizin sorumluluğunuzdadır. Fırsat aşamalarının nasıl kurulduğunu fırsat yönetimi sayfasında görebilirsiniz.

Form aracı: gönderim geldi

Web sitenizdeki form aracı, bir gönderim olduğunda size POST atar. Böylece gelen kaydı CRM'e yazabilir, satış ekibine bildirim gönderebilir, otomatik bir teşekkür e-postası tetikleyebilirsiniz. Bu, webhook'un en yalın kullanımıdır çünkü tek yönlüdür ve veri küçüktür.

GitHub: kod gönderildi

Yazılım tarafında en bilinen örnek. Depoya kod gönderildiğinde derleme sunucusunun haberi olur ve testler çalışır. GitHub'ın kendi tanımı da tam olarak bu: bir yazılım sisteminde gerçekleşen olaylara abone olup, olay gerçekleştiğinde sunucunuza otomatik veri teslimatı almak (docs.github.com, Eylül 2026'da kontrol edildi). GitHub imzayı X-Hub-Signature-256 başlığında, sha256= önekiyle gönderir ve karşılaştırmayı sabit zamanlı yapmanızı, düz == kullanmamanızı açıkça söyler (docs.github.com, Eylül 2026'da kontrol edildi).

WhatsApp: mesaj geldi, mesaj okundu

Mesajlaşma tarafında webhook, gelen mesajların ve durum güncellemelerinin tek dağıtım yoludur. WhatsApp Cloud API tarafında messages alanı hem kullanıcının işletmeye gönderdiği mesajları hem de işletmenin gönderdiği mesajların durumunu bildirir. Meta'nın belgesi, uç noktanız başarısız yanıt verdiğinde teslimatın azalan sıklıkla yedi güne kadar yeniden denendiğini ve bunun mükerrer bildirimlere yol açabileceğini yazıyor (developers.facebook.com, Eylül 2026'da kontrol edildi). Yedi gün boyunca tekrar gelebilen bir bildirim, idempotency'nin neden isteğe bağlı olmadığının en iyi örneğidir.

Discord webhook nedir ve nasıl oluşturulur

Discord webhook, bir Discord kanalına dışarıdan mesaj göndermeyi sağlayan tekil bir adrestir. Buradaki yön, şimdiye kadar anlattığımızın tersidir: Discord olayları size göndermez, siz Discord'a mesaj gönderirsiniz. Discord'un kendi tanımı da böyle: sunucudaki bir metin kanalına otomatik mesaj ve veri güncellemesi düşürmenin kolay yolu (support.discord.com, Eylül 2026'da kontrol edildi).

Bu yüzden Discord webhook'u genelde "gelen webhook" (incoming webhook) diye anılır. Slack'in kanal webhook'u, Microsoft Teams'in bağlayıcıları ve Telegram bot bildirimleri de aynı ailedendir: bildirim hedefi olurlar, olay kaynağı olmazlar.

Adım adım oluşturma

Discord'un yardım sayfasındaki adımlar şöyle (Eylül 2026'da kontrol edildi):

1. Sunucu ayarlarını açın ve Integrations sekmesine gidin.
2. Create Webhook düğmesine basın.
3. Açılan ekranda webhook'a bir isim verin, sol üstteki avatara tıklayarak görselini değiştirin ve açılır menüden mesajların düşeceği metin kanalını seçin.
4. Copy Webhook URL düğmesiyle adresi kopyalayın.

Adres https://discord.com/api/webhooks/<id>/<token> biçimindedir ve içindeki jeton, o kanala yazma yetkisinin kendisidir. Başka bir deyişle bu adres bir paroladır: herkese açık bir depoya, ekran görüntüsüne ya da istemci tarafı koda koymayın. Discord'un yardım sayfasındaki örnek, aynı adresi bir GitHub deposunun ayarlarına yapıştırıp depodaki değişiklikleri kanala düşürmeyi anlatıyor.

Kendi mesajınızı göndermek

Adresi aldıktan sonra tek yapmanız gereken oraya JSON gövdeli bir POST atmak. Discord'un geliştirici belgesinde bu uç nokta POST /webhooks/{webhook.id}/{webhook.token} olarak tanımlı; gövdede content alanı 2000 karaktere kadar metin alır, username ve avatar_url görünen adı ve görseli o mesaj için değiştirir, embeds ise en fazla 10 gömülü nesne kabul eder (docs.discord.com, Eylül 2026'da kontrol edildi).

curl -X POST "https://discord.com/api/webhooks/<id>/<token>" \
  -H "Content-Type: application/json" \
  -d '{
        "username": "Satış bildirimi",
        "content": "Fırsat kazanıldı: Analytical Engines yıllık sözleşme"
      }'

Discord varsayılan olarak 204 döner ve gövde yollamaz. Gönderdiğiniz mesajı yanıtta görmek isterseniz adrese ?wait=true ekleyin; o zaman oluşturulan mesaj nesnesi döner.

Discord'u CRM bildirim hedefi olarak kullanmak

Pratikte en sık kurulan zincir şu: CRM'de bir olay olur, olay bir otomasyon aracına ya da kendi sunucunuza düşer, o da Discord'a mesaj atar. Discord tarafı yalnızca son halkadır.

Pinlyx tarafında Discord'u ayrı bir alıcı yazmadan bildirim hedefi yapabilirsiniz: Entegrasyonlar ekranındaki bildirim kanalları bölümünde Discord'u seçip kanalın gelen webhook adresini yapıştırırsınız, hangi olaylarda bildirim istediğinizi işaretlersiniz. Bu yol yalnızca bildirim içindir: mesaj düşer, ama Discord'dan gelen yanıt CRM'e geri akmaz. Karşılıklı konuşmayı tek yerden yönetmek istiyorsanız aradığınız şey webhook değil, tek gelen kutusu yaklaşımıdır. Discord bildirim kanalı ücretli planlarda açıktır ve giden webhook'lardan ayrı bir özelliktir.

Güvenlik: imzayı doğrulamak ve sahte isteği elemek

Webhook uç noktanız internete açıktır ve kimlik doğrulaması yoktur. Adresi bilen herkes oraya istek atabilir. Sizi koruyan tek şey imzadır ve imzayı doğrulamayan bir uç nokta, "şu siparişi ödendi işaretle" diyen herkese açık bir düğmedir.

HMAC imzası nasıl çalışır

Gönderen taraf, istek gövdesinin baytlarını alır, sizinle paylaştığı gizli anahtarla HMAC-SHA256 hesaplar ve sonucu onaltılık bir dize olarak başlığa koyar. Siz aynı hesabı kendi tarafınızda yaparsınız. İki değer aynıysa, isteği gönderen tarafın gizli anahtarı bildiği kanıtlanmış olur. Anahtar hiçbir zaman ağda gitmez; giden yalnızca özettir.

Pinlyx tarafında imza X-Webhook-Signature başlığında, sha256= önekiyle ve küçük harfli onaltılık biçimde gelir. Hesap, zarfın tamamının (yani {"event":...,"data":{...}} gövdesinin) baytları üzerinden yapılır.

Node.js ile doğrulama

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Ham gövde şart: JSON'a çevirip yeniden metne dökerseniz imza tutmaz.
app.post('/hooks/crm', express.raw({ type: 'application/json' }), (req, res) => {
  const gelen = req.get('X-Webhook-Signature') || '';
  const beklenen = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  const a = Buffer.from(beklenen);
  const b = Buffer.from(gelen);
  // Uzunluk farklıysa timingSafeEqual hata fırlatır, önce onu eleyin.
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('imza gecersiz');
  }

  const zarf = JSON.parse(req.body.toString('utf8'));

  res.status(200).end();   // önce 2xx dönün
  kuyrugaAl(zarf);         // ağır işi sonra yapın
});

Python ile doğrulama

import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SIR = os.environ["WEBHOOK_SECRET"].encode()

@app.post("/hooks/crm")
def hook():
    ham = request.get_data()          # ham bayt; request.json kullanmayın
    gelen = request.headers.get("X-Webhook-Signature", "")
    beklenen = "sha256=" + hmac.new(SIR, ham, hashlib.sha256).hexdigest()

    # compare_digest sabit zamanlıdır; "==" kullanmayın
    if not hmac.compare_digest(beklenen, gelen):
        abort(401)

    # Tekrar saldırısına karşı: 5 dakikadan eski istek kabul edilmez
    damga = int(request.headers.get("X-Webhook-Timestamp", "0"))
    if abs(time.time() - damga) > 300:
        abort(400)

    kuyruga_al(request.get_json())
    return "", 200

Neden sabit zamanlı karşılaştırma

Sıradan dize karşılaştırması, ilk farklı karakterde durur. Bu da doğru tahmin edilen her karakterin karşılaştırmayı bir nebze uzatması demektir. Saldırgan yeterince çok deneme yapıp süreleri ölçerse imzayı karakter karakter bulabilir. Sabit zamanlı karşılaştırma (Node'da crypto.timingSafeEqual, Python'da hmac.compare_digest, PHP'de hash_equals, Go'da hmac.Equal) bütün baytlara bakar ve süreyi içeriğe bağlı olmaktan çıkarır. GitHub bu konuda açık: düz == kullanmayın (docs.github.com, Eylül 2026'da kontrol edildi).

Tekrar saldırısı ve zaman damgası

İmza doğru olsa bile, birisi geçerli bir isteği yakalayıp sonra tekrar tekrar gönderebilir. İmza aynı gövdeden hesaplandığı için her seferinde tutar. Çözüm, gövdeye ya da başlığa zaman damgası koymak ve alıcıda bir tolerans penceresi uygulamaktır. Stripe'ın kütüphaneleri varsayılan olarak 5 dakikalık tolerans kullanıyor ve toleransı sıfıra çekmemeniz gerektiğini yazıyor, çünkü sıfır güncellik denetimini tamamen kapatır (docs.stripe.com/webhooks, Eylül 2026'da kontrol edildi).

Pinlyx X-Webhook-Timestamp başlığını Unix saniyesi olarak gönderir. Bu değeri kendi saatinizle karşılaştırıp makul olmayan istekleri eleyebilirsiniz. Sunucunuzun saatinin doğru olmasına dikkat edin; saati kaymış bir makine, geçerli istekleri reddetmeye başlar.

Gizli anahtarı yönetmek

Gizli anahtar bir paroladır ve parola gibi davranmayı hak eder.

• Kodun içine yazmayın. Ortam değişkeninde ya da bir sır yöneticisinde dursun. Depoya girmiş bir anahtar, depo özel olsa bile açılmış sayılır.
• Bir kez gösterilir. Pinlyx uç noktayı oluştururken anahtarı tek seferlik gösterir; kaybederseniz okuma imkânı yoktur, yenilemeniz gerekir.
• Belirli aralıklarla yenileyin. Panelde "İmzalama anahtarını yenile" seçeneği vardır. Yenilediğiniz anda eski anahtar geçersiz olur, yani önce sunucunuzu güncelleyin, sonra yenileyin. Stripe da düzenli yenilemeyi öneriyor.
• Her uç noktaya ayrı anahtar. Üç farklı sisteme üç ayrı uç nokta tanımlıyorsanız üçünün anahtarı ayrıdır; birinin sızması diğerlerini etkilemez.

Ek katmanlar: HTTPS, IP kısıtı ve gövdenin kendisi

HTTPS zorunlu olsun. Düz HTTP üzerinden giden bir webhook, gövdeyi ve imzayı yolda okunabilir kılar. Pinlyx zaten https:// dışındaki adresleri kabul etmiyor.

IP kısıtı ikinci kilittir, birincisi değil. Sağlayıcı sabit IP aralıklarından gönderiyorsa güvenlik duvarınızda yalnızca onlara izin verebilirsiniz. Ama bu, imzanın yerini tutmaz: IP taklit edilebilir, sağlayıcı aralığını habersiz değiştirebilir ve aynı bulut sağlayıcısındaki başka bir müşteri aynı aralıkta olabilir. İmza ile birlikte kullanın.

Gövdeye körü körüne güvenmeyin. İmza, isteğin kaynağının doğruluğunu kanıtlar; içeriğin doğruluğunu değil. Gövdedeki metin alanları, o sistemde bir kullanıcının yazdığı serbest metin olabilir. Veritabanına yazarken kaçış kurallarını, arayüzde gösterirken HTML kaçışını uygulayın.

Yeniden deneme ve idempotency: aynı olay iki kez gelirse

Webhook sistemlerinin yarısı gönderme, yarısı yeniden gönderme meselesidir. Uç noktanız kapalıyken olan bir şeyin kaybolmaması gerekir, ama kaybolmasın diye tekrar denemek de mükerrer teslimat üretir. İki tarafın sorumluluğu şöyle bölünür: tekrar denemek göndericinin işi, tekrarı zararsız kılmak alıcının işi.

Başarısızlık neye denir

Bir teslimat şu durumlarda başarısız sayılır: 2xx dışında bir durum kodu, zaman aşımı, bağlantı kurulamaması ya da TLS hatası. Ama hepsi aynı muameleyi görmez ve bu ayrım önemlidir.

Pinlyx tarafında 408, 429 ve bütün 5xx yanıtları geçici sayılır ve yeniden denenir. Diğer 4xx yanıtları (400, 401, 403, 404, 422 gibi) kalıcı sayılır ve yeniden denenmez: alıcı isteği açıkça reddetmiştir, aynısını tekrar göndermek yalnızca gürültü üretir. Bu davranışın pratik sonucu şu: kendi kodunuzdaki bir hata yüzünden 500 dönüyorsanız olay geri gelir, ama imza kontrolünde 401 dönüyorsanız o olay bir daha gelmez ve elle yeniden denemeniz gerekir.

Bekleme takvimi

Yeniden denemeler üstel bekleme ile yapılır: her denemede süre uzar, böylece sizin sunucunuz ayağa kalkarken üstüne yığılmaz. Pinlyx en fazla 8 deneme yapar ve aralar şöyledir:

Her aralığa artı eksi yüzde 20 oynama (jitter) eklenir. Bunun nedeni şu: yüzlerce teslimat aynı anda başarısız olduysa ve hepsi tam olarak bir dakika sonra tekrar denerse, sunucunuz tam toparlanırken aynı anda ikinci bir dalga yer. Rastgele oynama dalgayı yayar.

Sekizinci denemeden sonra teslimat "tükendi" olarak işaretlenir ve bırakılır. Bu, olayın yaklaşık iki buçuk günlük bir kurtarma penceresi olduğu anlamına gelir; bu süre içinde uç noktanızı ayağa kaldırırsanız veri kaybı olmaz.

Uç noktanın otomatik kapanması

Ayrı bir emniyet daha var: bir uç nokta art arda 20 kez başarısız olursa kendiliğinden devre dışı bırakılır. Amaç, aylardır kapalı olan bir adrese sonsuza kadar istek yağdırmamaktır. Devre dışı kalan uç noktaya bekleyen teslimatlar da gönderilmez.

Bunun sizin açınızdan sonucu şudur: uzun bir bakım penceresinden çıktığınızda uç noktanızın hâlâ etkin olduğunu doğrulayın. Başarılı tek bir teslimat sayacı sıfırlar.

Idempotency: aynı olayı iki kez işlememek

Idempotent bir işleyici, aynı olayı iki kez aldığında bir kez almışçasına davranır. Bu, webhook kurulumunun en çok atlanan ve en pahalı sonuç doğuran kısmıdır. Fatura iki kez kesilir, müşteriye iki kez e-posta gider, stok iki kez düşer.

Doğru anahtar, olayın kimliğidir. Pinlyx bunu hem X-Webhook-Event-Id başlığında hem de zarftaki id alanında gönderir; yeniden denemelerde bu değer değişmez. Uygulaması kısa:

-- Tek satırlık koruma: aynı olay ikinci kez gelirse yazma çakışır
CREATE TABLE islenen_olaylar (
  olay_id   TEXT PRIMARY KEY,
  tur       TEXT NOT NULL,
  islendi   TIMESTAMPTZ NOT NULL DEFAULT now()
);

async function isle(zarf) {
  const eklendi = await db.query(
    'INSERT INTO islenen_olaylar (olay_id, tur) VALUES ($1, $2) ON CONFLICT DO NOTHING',
    [zarf.id, zarf.event],
  );
  if (eklendi.rowCount === 0) return;   // daha önce işlenmiş, sessizce çık

  await gercekIs(zarf);                 // fatura kes, satır ekle, bildirim gönder
}

Üç ayrıntı işi sağlamlaştırır. Birincisi, kaydı işten önce atmak: iş yarıda kalırsa tekrar denenebilsin diye işlemi (transaction) tek parça tutun. İkincisi, tabloyu şişirmemek için eski satırları temizlemek; iki buçuk günü aşan bir olay zaten tekrar gelmeyecektir, ama rahat olmak için birkaç hafta tutabilirsiniz. Üçüncüsü, olay kimliğinin yanına türü de yazmak; ayıklarken çok işinize yarar.

Sıra garantisi yoktur

Son bir tuzak: olaylar oluşma sırasında gelmeyebilir. İki olay neredeyse aynı anda üretildiyse, birinin teslimatı yeniden denemeye takılırken diğeri geçebilir. Yani "fırsat aşaması değişti" olayı, "fırsat oluşturuldu" olayından önce elinize geçebilir.

Bunun pratik karşılığı, işleyicinizin eksik önkoşula dayanıklı olmasıdır. İlgili kaydı bulamadığınızda hata fırlatmak yerine kaydı API'den çekin ya da olayı kısa bir gecikmeyle yeniden kuyruğa alın. Zarftaki zaman alanına bakarak eski bir olayın yeni veriyi ezmesini de engelleyebilirsiniz.

Webhook hataları ve ayıklama: hangi belirti neye işaret eder

Webhook kurulumlarında sorunların büyük kısmı beş başlıkta toplanır. Teslimat kaydı bu noktada en değerli araçtır: ne gönderildi, ne zaman, hangi kod döndü, kaçıncı denemeydi.

İmza uyuşmazlığının en sık üç sebebi

Ayrıştırılmış gövdeyle hesaplamak. JSON'u nesneye çevirip tekrar metne döktüğünüzde boşluklar, alan sırası ve sayıların yazımı değişebilir. Aynı anlam, farklı baytlar, farklı özet. Çerçevenizden ham baytları isteyin.

Yanlış anahtar. Birden fazla uç noktanız varsa her birinin anahtarı ayrıdır. Test ortamı ile canlı ortamın anahtarları da ayrıdır.

Önek karışıklığı. Bazı sağlayıcılar imzayı çıplak onaltılık dize olarak, bazıları sha256= önekiyle gönderir. Beklenen değeri kurarken aynı biçimi kullanın; yoksa iki doğru değer eşit görünmez.

Ayıklama sırası

Bir entegrasyon çalışmadığında sırayı bozmadan ilerlemek en hızlı yoldur.

1. Adresi webhook.site ile test edin. Uç noktayı geçici olarak oraya yönlendirin. İstek geliyorsa gönderici tarafı sağlam, sorun sizin kodunuzda.
2. Test gönderimi yapın. Panelden tek tuşla bir test olayı yollayın. Böylece gerçek bir olay beklemeden yolu deneyebilirsiniz.
3. Teslimat kaydına bakın. Kayıt, uç noktanızın döndürdüğü durum kodunu ve yanıt gövdesinin başını gösterir. "Olay tetiklendi mi" tartışması burada biter.
4. Yanıt gövdenize hata sebebini yazın. 400 dönerken gövdeye "imza uyuşmadı" yazarsanız, o metin teslimat kaydında görünür ve bir dahaki sefere on dakika kazanırsınız.
5. Düzelttikten sonra elle yeniden deneyin. Kaydın üzerindeki yeniden deneme seçeneği aynı olayı baştan kuyruğa alır.

Pinlyx webhook'ları: 26 olay, imzalı zarf ve okunabilir teslimat kaydı

Buraya kadar anlatılanlar her sağlayıcı için geçerli. Bu bölüm, aynı şeylerin Pinlyx tarafında somut olarak neye benzediğini gösteriyor. Baştan söyleyelim: giden webhook'lar Business planının özelliğidir. Ücretsiz planda ve Pro'da kapalıdır; API anahtarı, MCP sunucusu ve Zapier ile n8n bağlantıları da aynı plandadır. Plan kapsamı için fiyatlandırma sayfasına bakın.

Uç nokta nasıl kurulur

1. Panelde sol menüden Araçlar (Tools) altındaki Entegrasyonlar (Integrations) ekranını açın, oradan Webhook'lar bölümüne girin.
2. Yeni uç nokta (New endpoint) düğmesine basın. HTTPS adresinizi yazın; isterseniz kısa bir açıklama ekleyin, uç nokta çoğaldığında ayırt etmenizi sağlar.
3. Olayları seçin. Yalnızca ihtiyaç duyduklarınızı işaretleyin ya da hepsini almak için * (tüm olaylar) seçeneğini kullanın. Abonelik listesinde * joker değeri, "gelecekte eklenecekler dahil her şey" anlamına gelir.
4. Kaydedin. İmzalama anahtarı ekranda bir kez gösterilir. Kopyalayıp sunucunuzun ortam değişkenine koyun; sonradan okunamaz, yalnızca yenilenebilir.
5. Test olayı gönder ile bir webhook.test olayı yollayın. Bu test, o olaya abone olmasanız bile gider; amacı adresi, imza kontrolünü ve işleyicinizi gerçek bir olay gelmeden denemenizdir.
6. Uç noktanın satırındaki Son teslimatlar bölümünden teslimatları izleyin. Her satırda durum, olay türü, uç noktanızın döndürdüğü kod ve deneme sayısı vardır; başarısız olan bir teslimatı buradan elle yeniden deneyebilirsiniz.
7. Anahtarı değiştirmek istediğinizde Gizli anahtarı yenile seçeneğini kullanın. Eski anahtar aynı anda geçersiz olur, bu yüzden önce sunucunuzu yeni anahtarla güncelleyin.

Uç nokta sayısı 20 ile sınırlıdır, yani depo sisteminiz, iç bildirim aktarıcınız ve veri ambarınız kendi adresini ve kendi anahtarını alabilir. Ücretsiz hesap açıp paneli gezebilirsiniz; webhook ekranı yalnızca Business planında açılır, ücretsiz ve Pro hesapta kilitli görünür. Olay listesinin tamamı aşağıdaki tabloda duruyor.

Yayımlanan 26 olayın tamamı ve test olayı

Aşağıdaki liste, abone olabileceğiniz olayların tamamıdır. Her olayın örnek gövdesi panelde, olay seçiminin yanında duruyor; yani hangi alanların geleceğini tahmin etmeniz gerekmiyor.

Üç ayrıntı listeye bakarken gözden kaçıyor. Birincisi, kazanma ve kaybetme olayları aşama değişimiyle birlikte gelir: bir fırsat kazanılan sütuna taşındığında önce deal.stage_changed, sonra deal.won düşer. İkisine birden abone olduysanız tek hareketi iki kez saymayın. İkincisi, kayıtlarla ilgili olaylar hem kaydın sahibini hem de hareketi yapan kişiyi taşır; paylaşımlı çalışma alanında bir ekip arkadaşı başkasının kaydını düzenlediğinde bu ikisi farklıdır ve değişikliği doğru kişiye yazmak için ikisine de ihtiyacınız olur. Üçüncüsü, invoice.paid ile finance.transaction.created aynı anda gelir, çünkü gelir kaydı faturanın ödenmesiyle aynı işlemde yazılır. Muhasebe tarafında ikisini birden dinliyorsanız tek tahsilatı iki gelir olarak işlemeyin. Gelirin nerede toplandığını görmek isterseniz gelir kaynakları sayfası bu tarafı anlatıyor.

Teslimat davranışının özeti

• Zarf: { event, id, deliveredAt, data }. Olayın kendi alanları data içindedir.
• Başlıklar: X-Webhook-Signature, X-Webhook-Event, X-Webhook-Event-Id, X-Webhook-Attempt, X-Webhook-Timestamp.
• İmza: sha256= önekiyle, gövdenin uç nokta anahtarıyla hesaplanmış HMAC-SHA256 değeri.
• Zaman aşımı: deneme başına 30 saniye.
• Yeniden deneme: en fazla 8 deneme, 1 dakikadan 24 saate uzayan aralarla ve rastgele oynamayla. Kalıcı 4xx yanıtları tekrarlanmaz.
• Otomatik kapanma: art arda 20 başarısızlıkta uç nokta devre dışı kalır.
• Adres kuralı: yalnızca HTTPS; özel ağ ve geri döngü adreslerine teslimat yapılmaz.
• Kota: hesap başına 20 uç nokta.

Webhook'un yanındaki iki yüzey

Webhook yalnız çalışmaz. Olayın bildirdiği kaydı okumak ya da değiştirmek için genel REST API vardır: /v1/* altında, Authorization: Bearer ya da X-Api-Key başlığıyla, kapsamlı anahtarlarla ve tekrarlı isteklerin ikinci kez işlenmesini engelleyen Idempotency-Key desteğiyle. Üçüncü yüzey ise MCP sunucusudur; yapay zekâ istemcisinin aynı çalışma alanını okuyup yazmasını sağlar ve ayrıntısını sosyal medya MCP sunucusu yazısında anlattık. Üçü de aynı plandadır.

Kodsuz senaryo: fırsat kazanıldığında tabloya satır, kanala bildirim

Şimdi hepsini birleştirelim. Amaç şu: bir fırsat kazanıldığında Google E-Tablolar'daki satış takip dosyasına yeni bir satır düşsün ve ekip kanalına mesaj gitsin. Alıcı sunucu yazmadan, tek satır kod olmadan.

Araç olarak n8n kullanıyoruz, çünkü kendi sunucunuzda da çalıştırabilirsiniz. Make ya da Zapier ile akış neredeyse aynıdır; yalnızca düğüm adları değişir.

Adım adım

1. n8n'de yeni bir akış açın ve Webhook düğümünü ekleyin. Yöntem olarak POST seçin. Düğüm size iki adres verir: Test URL ve Production URL. İlk kurulumda Test URL ile ilerleyin.
2. "Listen for Test Event" deyin. n8n bu sırada gelen isteği bekler ve gövdeyi ekranda gösterir.
3. Pinlyx'te uç noktayı oluşturun. Entegrasyonlar altındaki Webhook'lar ekranından yeni uç nokta ekleyin, n8n'in verdiği adresi yapıştırın ve olay olarak yalnızca deal.won seçin. Anahtarı kopyalayın.
4. Test gönderimi yapın. Uç nokta satırından test gönderin. n8n ekranında webhook.test zarfını göreceksiniz; bu, adresin doğru olduğunun kanıtıdır.
5. Gerçek bir olayla veri yapısını yakalayın. Deneme amaçlı bir fırsatı kazanıldı işaretleyin. n8n bu kez deal.won zarfını gösterir ve alanları sonraki düğümlerde seçebilir hâle gelirsiniz.
6. İmzayı kontrol eden bir adım koyun. Webhook düğümünün Header auth seçeneği burada işinize yaramaz, çünkü uç noktaya kendi başlığınızı ekleyemezsiniz. Doğru yol bir Code düğümü: gövdenin ham hâlinden gizli anahtarla HMAC hesaplayıp X-Webhook-Signature başlığındaki değerle karşılaştırın, tutmuyorsa akışı durdurun.
7. Google Sheets düğümünü ekleyin. İşlem olarak satır ekleme seçin, hesabınızı bağlayın ve sütunları zarftaki alanlara eşleyin: data.title, data.value, data.contactId, data.closedAt.
8. Bildirim düğümünü ekleyin. Slack ya da Discord düğümüyle kanala mesaj gönderin. Mesaj metnine fırsat başlığını ve tutarı koyun.
9. Akışı yayına alın ve adresi güncelleyin. Yayına aldığınızda üretim adresi çalışmaya başlar; Pinlyx'teki uç noktanın adresini Production URL ile değiştirmeyi unutmayın. Bu, kurulumda en sık atlanan adımdır ve "test ederken çalışıyordu" cümlesinin sebebidir.

Aynı işi Pinlyx'in n8n düğümüyle yapmak

Ters yön de mümkün: n8n'den Pinlyx'e yazmak. Bunun için topluluk düğümü var. n8n'de Settings altındaki Community Nodes bölümünden n8n-nodes-crmsolid paketini kurarsınız (paket adı eski markayı taşır, paket adları değişmez), kimlik olarak API anahtarınızı girersiniz ve kişi oluşturma, güncelleme, listeleme, fırsat açma ve konuşma okuma işlemlerini akışınızda kullanabilirsiniz. Kurulum ayrıntıları n8n entegrasyonu sayfasında.

Böylece iki yön birden kurulmuş olur: webhook olayı dışarı taşır, düğüm dışarıdan içeri yazar. Aradaki akışı da görsel olarak kurarsınız.

Webhook mu, API mi, MCP mi: hangisi hangi iş için

Üçü de aynı veriye dokunur ama üçü farklı soruya cevap verir.

Pratikte üçü birlikte kullanılır. Webhook değişimi bildirir, API ayrıntıyı getirir ve kaydı günceller, MCP ise aynı yüzeyi bir asistanın kullanmasına açar. Doğru soru "hangisi daha iyi" değil, "bu iş hangi yönde akıyor" sorusudur.

Webhook'un çözmediği işler ve ne zaman başka yol daha doğru

Webhook bir taşıma mekanizmasıdır, sihirli bir entegrasyon değil. Şu işlerde tek başına yetmez.

Geçmiş veriyi taşımak. Webhook yalnız ileriye bakar. Kurulumdan önceki üç yılın kayıtlarını almanın yolu API ya da dışa aktarmadır. İlk yükleme ile canlı akışın sırasını da planlayın: önce toplu yükleme yapıp sonra webhook'u açarsanız aradaki boşlukta oluşan kayıtları kaçırırsınız. Doğru sıra, önce webhook'u açıp olayları kuyruğa almak, sonra toplu yüklemeyi yapmak ve kuyruğu idempotent şekilde işlemektir.

Kesin sıralı işleme. Olaylar sırasız gelebilir. Muhasebe kapanışı gibi sıraya duyarlı bir işi doğrudan webhook akışına bağlamayın; olayları toplayıp kendi tarafınızda zaman alanına göre sıralayın.

Toplu iş. Elli bin kaydı gece yarısı senkronlamak webhook'un işi değildir. Elli bin ayrı HTTP isteği hem sizin hem gönderenin tarafında israftır. Böyle işler için dışa aktarma ya da sayfalı API listelemesi doğru araçtır.

Karşılıklı iletişim. Bildirim webhook'u tek yönlüdür. Discord kanalına mesaj düşürmek kolaydır, ama müşteri o mesaja cevap verdiğinde cevabı CRM'e taşıyan bir yol yoktur. Konuşmayı yönetmek istiyorsanız kanalın kendisini bağlamanız gerekir.

Bir de dürüst bir sınır: her iş için Pinlyx doğru araç değil. Yalnızca kendi ürününüzün iç servisleri arasında olay taşıyacaksanız, aradaki CRM katmanına hiç ihtiyacınız yok; bir mesaj kuyruğu (RabbitMQ, Kafka ya da bulut sağlayıcınızın kuyruğu) daha doğru araçtır ve teslimat garantisi konusunda daha çok seçenek sunar. Aynı şekilde, ödeme altyapınızın olaylarını işleyecekseniz doğrudan ödeme sağlayıcısının webhook'unu dinleyin; araya bir CRM koymak gereksiz bir halka ekler. Webhook'u CRM tarafında kurmanın anlamı, olayın satış ve müşteri bağlamı taşımasıdır: kimin, hangi konuşmadan sonra, hangi aşamada kazanıldığı.

Kısa özet

Webhook, bir olay gerçekleştiğinde kaynak sistemin sizin adresinize POST atmasıdır. API'den farkı yöndür: yoklamada siz sorarsınız, webhookta olay size gelir. Kurulumu üç parçadır: bir HTTPS adresi, bir gizli anahtar ve olay seçimi.

Alıcı tarafta üç kural işi sağlama alır. Ham gövdeyle imzayı doğrulayın ve karşılaştırmayı sabit zamanlı yapın. Ağır işten önce 2xx dönün. Olay kimliğine göre tekilleştirin ki yeniden denenen bir teslimat aynı faturayı iki kez kesmesin.

Kod yazmak istemiyorsanız n8n, Make ya da Zapier size hazır bir adres verir ve gelen veriyi görsel bir akışta işler. Test için webhook.site, yerel geliştirme için ngrok işinizi kolaylaştırır.

Uç noktayı kendi sunucunuzda denemeden önce: Pinlyx'te ücretsiz hesap açın, kişilerinizi ve Telegram hesabınızı bağlayıp CRM tarafını kurun; webhook, API anahtarı ve n8n bağlantısı Business planındadır ve ücretsiz planda açılmaz, bunu baştan bilin. Uç noktayı açtığınızda 26 olayın tamamına, imzalı zarfa ve teslimat kaydına aynı ekrandan erişirsiniz. Ücretsiz hesap açın, kredi kartı gerekmez.

Aynı olayları bir yapay zekâ ajanının tetiklemesini isterseniz WhatsApp chatbot nasıl yapılır yazısı ajan tarafını kuruyor.

Sık sorulan sorular

Webhook Discord nedir?

Discord webhook'u, bir Discord kanalına dışarıdan mesaj göndermeyi sağlayan tekil bir adrestir. Sunucu ayarlarındaki Integrations sekmesinden "Create Webhook" ile oluşturulur, kanal seçilir ve "Copy Webhook URL" ile adres kopyalanır (support.discord.com, Eylül 2026'da kontrol edildi).

Yön önemlidir: Discord size olay göndermez, siz Discord'a mesaj gönderirsiniz. O adrese JSON gövdeli bir POST attığınızda mesaj kanalda görünür; content alanı 2000 karaktere kadar metin alır. Adres bir paroladır, herkese açık yerlerde paylaşmayın.

Webhook ile API arasındaki fark nedir?

Yön farkıdır. API'yi siz çağırırsınız: "yeni bir şey var mı" diye sorarsınız. Webhookta çağıran taraf sistemdir: bir şey olduğunda size POST atar.

Sonuçları da farklıdır. Yoklama boşa giden çok istek üretir ve aralığının yarısı kadar geç kalır; webhook yalnızca olay olduğunda gelir ve genelde bir saniyenin altındadır. Buna karşılık webhook, sizin tarafınızda açık bir HTTPS adresi, imza doğrulaması ve idempotency ister. Çoğu olgun entegrasyon ikisini birlikte kullanır.

Webhook URL nasıl alınır?

Kimin gönderdiğine göre değişir. Bir sistemden olay alacaksanız, adresi siz üretirsiniz: kendi sunucunuzdaki bir POST yolu, bir bulut fonksiyonu ya da n8n, Make veya Zapier'in size verdiği hazır adres. Sonra bu adresi kaynak sistemin webhook ekranına yazarsınız.

Bir kanala mesaj göndereceksiniz (Discord, Slack gibi), adresi o platform üretir ve panelinden kopyalarsınız. Hızlı denemek için webhook.site anında bir adres verir ve oraya gelen isteği başlıklarıyla gösterir.

Webhook güvenli mi?

Doğru kurulduğunda evet, kurulmadığında hayır. Uç nokta internete açıktır ve adresi bilen herkes istek atabilir; sizi koruyan şey imzadır.

Asgari kontrol listesi: yalnızca HTTPS kullanın, gizli anahtarı ortam değişkeninde tutun, her istekte ham gövdeden HMAC hesaplayıp başlıktaki imzayla sabit zamanlı karşılaştırın, zaman damgasına makul bir tolerans uygulayın ve anahtarı belirli aralıklarla yenileyin. İsterseniz güvenlik duvarında sağlayıcının IP aralığına izin verin, ama bunu imzanın yerine değil yanına koyun.

Webhook kod bilmeden kullanılabilir mi?

Evet. n8n'in Webhook düğümü, Make'in custom webhook modülü ve "Webhooks by Zapier" size hazır bir adres verir; gelen veriyi görsel bir akışta işleyip tabloya, sohbet kanalına ya da başka bir uygulamaya bağlarsınız.

İki kısıtı bilin: Zapier'de webhook tetikleyicileri ücretsiz planda yoktur (help.zapier.com, Eylül 2026'da kontrol edildi), Make'te bir webhook beş gün boyunca hiçbir senaryoya bağlı kalmazsa kendiliğinden devre dışı kalır (help.make.com, Eylül 2026'da kontrol edildi). İmza doğrulamasını kodsuz araçta yapmak da mümkündür ama küçük bir kod adımı gerektirir; yapmayacaksanız en azından adresi tahmin edilmez tutun.

Webhook başarısız olursa ne olur?

Uç noktanız 2xx dönmezse ya da zaman aşımına uğrarsa gönderen taraf yeniden dener. Pinlyx en fazla 8 deneme yapar; aralar 1 dakika, 5 dakika, 15 dakika, 1 saat, 6 saat ve sonra 24 saatlik adımlarla uzar, her aralığa rastgele oynama eklenir. Yani yaklaşık iki buçuk günlük bir kurtarma pencereniz olur.

İstisna: 408 ve 429 dışındaki 4xx yanıtları kalıcı sayılır ve yeniden denenmez, çünkü alıcı isteği açıkça reddetmiştir. Art arda 20 başarısızlıkta uç nokta kendiliğinden devre dışı kalır. Teslimat kaydından her denemeyi görebilir, sorunu düzelttikten sonra elle yeniden deneyebilirsiniz.

Pinlyx webhook'ları hangi planda?

Business planında. Ücretsiz planda ve Pro'da kapalıdır. Aynı plan API anahtarını, MCP sunucusunu ve Zapier ile n8n bağlantılarını da içerir; hesap başına 20 uç nokta tanımlayabilirsiniz. Plan kapsamı için fiyatlandırma sayfasına bakın.

Ücretsiz plan, Telegram hesabı ve kişiler CRM'i etrafında kurulur: etiket, not, özel alan, aktivite geçmişi, satış panoları ve CSV içe aktarma. Webhook'a bugün ihtiyacınız yoksa oradan başlayıp sonradan yükseltebilirsiniz.

WhatsApp webhook nedir?

WhatsApp Cloud API tarafında webhook, gelen mesajların ve giden mesajların durum güncellemelerinin işletmeye ulaştırılma yoludur. messages alanına abone olduğunuzda kullanıcının yazdığı mesajlar ve gönderdiğiniz mesajların durumu uç noktanıza düşer (developers.facebook.com, Eylül 2026'da kontrol edildi).

Dikkat edilecek nokta mükerrer teslimattır: Meta'nın belgesine göre uç noktanız başarısız yanıt verdiğinde teslimat azalan sıklıkla yedi güne kadar tekrar denenir ve bu, aynı bildirimin birden çok kez gelmesine yol açabilir. Olay kimliğine göre tekilleştirme burada zorunludur. Pinlyx tarafında WhatsApp bağlantısı ücretli planlarda kurulur ve gelen mesajlar tek gelen kutusuna düşer; kendi webhook uç noktanızı yönetmeniz gerekmez.

Webhook'ta hangi doğrulama başlığı kullanılır?

Standart yoktur, sağlayıcıya göre değişir. GitHub X-Hub-Signature-256, Shopify X-Shopify-Hmac-Sha256, Stripe Stripe-Signature, Pinlyx ise X-Webhook-Signature kullanır. Ortak nokta, gövdenin gizli anahtarla hesaplanmış HMAC özetinin taşınmasıdır.

Biçim de değişebilir: kimi sağlayıcı çıplak onaltılık dize, kimi sha256= öneki, kimi de base64 kullanır. Stripe gibi bazı sağlayıcılar zaman damgasını da aynı başlığa koyar ve imzayı "zaman damgası nokta gövde" dizisi üzerinden hesaplar. Entegrasyona başlarken belgedeki tam biçimi okuyun; imza uyuşmazlıklarının büyük kısmı bu ayrıntıdan çıkar.

Aynı olayı hem webhook hem API ile takip etmek gerekir mi?

Kritik iş akışlarında evet. Webhook birincil yoldur ve hızlıdır; günde bir çalışan bir mutabakat işi ise kaçan olmadığını doğrular. Shopify'ın kendi belgesi de teslimatın her zaman garanti edilmediğini ve yedek olarak periyodik kontrol önerdiğini yazıyor (shopify.dev, Eylül 2026'da kontrol edildi).

Bu ikili desenin maliyeti düşüktür: yoklama artık dakikada değil günde bir çalışır, yani kota tüketimi ihmal edilebilir; buna karşılık sessiz veri kaybı ihtimalini ortadan kaldırır.

İlgili yazılar

• n8n nedir: kod yazmadan iş akışı otomasyonu, kurulum ve Zapier karşılaştırması.
• Sosyal medya MCP sunucusu: yapay zekâ asistanına CRM ve DM kutusu erişimi vermenin protokolü.
• Türkçe yapay zekâ müşteri temsilcisi: gelen mesajları otomatik yanıtlamanın kurulumu ve sınırları.
• Excel yerine CRM'e geçiş rehberi: tabloyu bırakmadan önce hangi verinin nereye taşınacağı.
• Türkiye'de CRM kullanım oranları: hangi ölçekte kim hangi aracı kullanıyor.