Entegrasyon & Webhook Motoru
TotalApp ile onunla konuşan her dış platform arasındaki ön kapı. Shopify, WooCommerce, Odoo, Wix ve özel sistemlerden gelen webhook patlamalarını emer, her birini milisaniyeler içinde kabul eder ve gerçek işi güvenli şekilde arka planda işler — böylece bir entegrasyondaki trafik artışı uygulamanın geri kalanını asla yavaşlatmaz.
Entegrasyon & Webhook Motoru Nedir?
TotalApp'in bağlandığı her dış platform — bir e-ticaret mağazası, bir ERP sistemi, bir web sitesi oluşturucu — TotalApp'e "az önce bir şey oldu" demenin bir yoluna ihtiyaç duyar. Yeni bir sipariş verildi. Bir ürün güncellendi. Bir müşteri kaydı değişti. Neredeyse her platformun bunun için kullandığı mekanizma bir webhook'tur: olay gerçekleştiği anda, dış platform TotalApp'in açığa çıkardığı bir URL'ye doğrudan bir HTTP isteği fırlatır ve olayın ayrıntılarını istek gövdesinde taşır.
Bu motorun çözdüğü sorun, bu isteğin TotalApp tarafında ne olduğudur. Eğer TotalApp her webhook'u — doğrulamak, dönüştürmek, depoya yazmak, belki başka bir yapay zeka motorunu çağırmak gibi — dış platform hâlâ bir yanıt beklerken tamamen işlemeye çalışsaydı, iki şey ters giderdi. Birincisi, bu işlem birkaç saniyeden fazla sürerse, dış platform zaman aşımına uğrar ve teslimatı başarısız sayar, dolayısıyla tekrar dener ve aynı olay artık iki kez işlenmiş olabilir. İkincisi, yüzlerce isteğin aynı anda gelmesi durumunda — bir flaş satış, toplu bir ürün içe aktarma — uygulamanın ana sunucusu, o anda TotalApp'i gerçekten kullanan kişilere hizmet etmek yerine tüm zamanını bu işi yapmaya harcar.
Entegrasyon & Webhook Motoru, tam olarak bu iki sorunu önlemek için var. Her gelen webhook'u iki ayrı ana böler: anında gerçekleşen bir kabul adımı (böylece gönderen asla zaman aşımına uğramaz ve asla tekrar denemesi gerekmez) ve daha sonra, arka planda, uygulamanın geri kalanının kaldırabileceği bir hızda gerçekleşen bir işleme adımı.
Tek cümlede
Motor, gönderene milisaniyeler içinde "aldım, bunu ben halledeceğim" der, ardından asıl işi — güvenli şekilde, otomatik tekrar denemelerle — o ilk isteğin görüş alanının tamamen dışında yapar.
Nasıl Çalışır — Anında Kabul Et, Sonra İşle
Her gelen webhook aynı iki aşamalı yaşam döngüsünden geçer:
| Aşama | Ne olur |
|---|---|
| 1. Kabul Et & Kuyruğa Al | Motor, isteğin kesinlikle ihtiyaç duyduğu iki bilgiyi kontrol eder — hangi çalışma alanına ait olduğu ve hangi platformun gönderdiği — varsa isteğin imzasını doğrular ve olayı anında dahili bir kuyruğa yerleştirir. Gönderen, gerçek işleme başlamadan önce, milisaniyeler içinde "kabul edildi" yanıtı alır. |
| 2. Arka Planda İşle | Bir arka plan işçisi, olayları kuyruktan kontrollü bir hızda (aynı anda hepsini değil, bir avuç kadar) alır ve gerçek entegrasyon mantığını çalıştırır — örneğin, doğrulanmış bir kaydı bir Schema & Data Engine koleksiyonuna yazmak veya içeriği puanlama için Matris Ajanı'e beslemek. Bu adım geçici bir nedenle başarısız olursa, olay başarısız olarak işaretlenmeden önce otomatik olarak birkaç kez tekrar denenir. |
Neden her şeyi anında işlemiyoruz?
Çünkü gönderen sabırla bekleyen bir insan değil, bir makinedir — çoğu platform bir webhook teslimatına, başarısız sayıp yeniden göndermeden önce yalnızca birkaç saniye tanır. TotalApp tüm işini satır içi (inline) yapsaydı, yavaş bir an (yoğun bir sunucu, büyük bir payload, alt akıştaki bir motorun her zamankinden uzun sürmesi) gönderene bir başarısızlık gibi görünürdü ve aynı olayın tekrarlanan teslimatlarını tetiklerdi. "Kabul et"i "işle"den ayırmak, bu sorun sınıfının tamamını ortadan kaldırır.
Girdi — Her Gelen Webhook'un Taşıması Gerekenler
Hangi platform gönderirse göndersin, bu motor tarafından kabul edilen her webhook, platformun dahil ettiği olaya özgü verilerin yanı sıra aynı iki zorunlu bilgiyi taşır:
Çalışma Alanı Kimliği
Bu olayın hangi TotalApp çalışma alanına (tenant) ait olduğu. Motorun dokunduğu her koleksiyon, günlük ve alt akış kaydı bu çalışma alanına özeldir, başkasına değil — bir çalışma alanının webhook trafiği asla başka birine görünür değildir.
Kaynak Platform
Olayı hangi sistemin gönderdiği — Shopify, WooCommerce, Odoo, Wix veya özel bir entegrasyon. Bu, isteği doğrulamak için hangi imza sırrının (varsa) kullanılacağını ve olayı hangi alt akış mantığının işleyeceğini belirler.
Olay Adı (isteğe bağlı)
Ne olduğuna dair kısa bir etiket — ör. order.created, product.updated — filtreleme, günlükleme ve olayı doğru alt akış işleyicisine yönlendirmek için kullanılır.
Olay Payload'ı
Kaynak platformun olayın kendisi hakkında dahil ettiği her şey — bir siparişin kalemleri, bir ürünün güncellenen fiyatı, bir müşterinin iletişim bilgileri. Bu kısım tamamen platforma özgüdür ve olduğu gibi geçirilir.
Yapılandırıldığında imza doğrulaması
Bir çalışma alanı belirli bir kaynak platform için bir imzalama sırrı kaydettiyse, o platformdan gelen her istek eşleşen bir imza header'ı içermek zorundadır. Eksik veya yanlış imzalı bir istek, kuyruğa hiç ulaşmadan reddedilir. Bir sır kaydedilene kadar, istekler bu kontrol olmadan kabul edilir — ilk kurulum sırasında faydalıdır, ancak gerçek bir entegrasyonla canlıya geçmeden önce her zaman bir imzalama sırrı yapılandırılmalıdır.
Çıktı — Geriye Ne Döner
Motor, orijinal webhook isteğine neredeyse anında yanıt verir ve ayrıca bir olayın ilerlemesini daha sonra kontrol etmenin bir yolunu sunar:
| Sonuç | Anlamı |
|---|---|
| Kabul Edildi (202) | Olay temel kontrollerinden geçti ve kuyruğa yerleştirildi. Yanıt, ilerlemesini daha sonra kontrol etmek için kullanılabilecek bir iş kimliği içerir. Bu, olayın işlemesinin bittiği anlamına gelmez — yalnızca güvenli şekilde alındığı anlamına gelir. |
| Eksik çalışma alanı veya platform (400) | İstek, iki zorunlu tanımlayıcıdan birini içermiyordu veya çalışma alanı kimliği gerçek bir çalışma alanına karşılık gelmiyordu. Hiçbir şey kuyruğa alınmaz. |
| Geçersiz imza (401) | Bu platform için bir imzalama sırrı yapılandırılmış, ancak isteğin imzası onunla eşleşmedi. İstek doğrudan reddedilir — bu, motorun sahte webhook trafiğine karşı birincil savunmasıdır. |
| Payload çok büyük (413) | İstek gövdesi motorun boyut sınırını aştı. Aşırı büyük payload'lar, kabul edilip daha sonra işleme sırasında başarısız olmaya bırakılmak yerine reddedilir. |
| İş durumu — kuyrukta / işleniyor / tamamlandı / hata | Kabul anında dönen kimlikle iş durumu endpoint'ini sorgulamak, o olayın yaşam döngüsünde tam olarak nerede olduğunu, sonunda başarısız olduysa belirli hata mesajı da dahil olmak üzere, bildirir. |
Kabul edilmek, işlenmekle aynı şey değildir
202 Accepted yanıtı bir onay değil, bir alındı belgesidir. Olayın hâlâ bir arka plan işçisi tarafından alınması ve gerçek işleme mantığından geçirilmesi gerekir — bu da başarısız olabilir, tekrar denenebilir ve sonunda başarılı olabilir veya vazgeçebilir. Bir olayın nihai sonucunu bilmesi gereken herhangi bir entegrasyon, kabulün tamamlanma anlamına geldiğini varsaymak yerine daha sonra iş durumunu kontrol etmelidir.
Güvenilirlik — Tekrar Denemeler, Geri Çekilme ve İzolasyon
Arka plan işleme, olayın kendisiyle hiçbir ilgisi olmayan nedenlerle başarısız olabileceğinden — anlık bir disk sorunu, meşgul bir alt akış motoru — motor, başarısızlıkları ölümcül değil beklenen ve kurtarılabilir olarak ele alır:
Otomatik Tekrar Denemeler
İşlenmesi başarısız olan bir olay, denemeler arasında artan bir gecikmeyle (birkaç saniye, ardından daha uzun) en fazla üç kez otomatik olarak tekrar denenir. Yalnızca tüm denemeler tükendikten sonra olay kalıcı olarak başarısız olarak işaretlenir.
Kontrollü Eşzamanlılık
Kuyrukta kaç olay beklerse beklesin, arka plan işçisi aynı anda yalnızca küçük, sabit sayıda olayı işler. Bin olaylık bir patlama, uygulamayı bir anda boğmak yerine sorunsuz bir şekilde emilir.
İzole Edilmiş Başarısızlıklar
Bozuk veya olağandışı büyüklükteki bir olayın işlenmesindeki başarısızlık, kuyruktaki başka hiçbir olayı asla etkilemez ve kabul endpoint'inin kendisini asla çökertmez — önceki bir olay tekrar denemede takılı kalsa bile, bir gönderen her zaman yeni bir olayı başarıyla teslim edebilir.
Kalıcı Geçmiş
İşlemesi biten her olay — başarılı ya da değil — o çalışma alanının kendi etkinlik günlüğüne kaydedilir, böylece daha sonra "bu hafta webhook'larıma ne oldu" incelemesi, o anı yakalamaya bağlı değildir.
Bir yeniden başlatmanın kaybedebileceği ve kaybedemeyeceği şeyler
İşlemesi zaten biten olaylar — başarılı olsun ya da tekrar denemeleri tükensin — kalıcı olarak kaydedilir ve kaybedilemez. Sunucunun yeniden başlatıldığı tam anda hâlâ bekleyen veya tekrar deneme sürecinde olan olaylar, işleri bitene kadar yalnızca bellekte var oldukları için risk altındaki tek olaylardır. Çoğu webhook entegrasyonu için bu kabul edilebilir bir ödünleşimdir, çünkü gönderen platformun kendi tekrar deneme davranışı (çoğu platform başarısız/zaman aşımına uğrayan teslimatları kendi programına göre tekrar dener) doğal bir güvenlik ağı sağlar.
Webhook Trafiğini Güvenilir Tutmak
Bir çalışma alanının webhook URL'sini bilen herkes, prensip olarak ona sahte olaylar gönderebilir. Bunu önlemek için, her çalışma alanı kaynak platform başına bir imzalama sırrı kaydedebilir — aynı sır hem TotalApp'te hem de dış platformun tarafında yapılandırılır ve her gerçek webhook teslimatı bu sırdan hesaplanan bir imza içerir.
Bir platform için bir imzalama sırrı kaydedildikten sonra, o platformdan olduğunu iddia eden her gelecek istek eşleşen bir imza sunmak zorundadır — başka her şey, kuyruğa ulaşmadan, alt akıştaki hiçbir veriye dokunmadan önce reddedilir.
Canlıya geçmeden önce bunu kurun
İlk kurulum sırasında, bir imzalama sırrı kaydedilmeden önce, motor yeni bir entegrasyondan gelen webhook'ları uçtan uca test edilebilmesi için yine de kabul eder. Bir entegrasyon canlıya geçip gerçek verileri işlemeye başladığında, bir imzalama sırrı kaydetmek bu penceredeyi kapatır ve her üretim entegrasyonu için şiddetle tavsiye edilir.
Son Kullanıcılar Bunu Nasıl Kullanıyor?
Bir Dış Platformu Bağlama
Bir entegrasyon ayarları ekranından, bir çalışma alanı yöneticisi:
- Hangi platformun bağlanacağını seçer — Shopify, WooCommerce, Odoo, Wix veya özel bir sistem.
- TotalApp'in o çalışma alanı için oluşturduğu webhook URL'sini kopyalar ve dış platformun kendi webhook ayarlarına yapıştırır.
- İsteğe bağlı olarak bir imzalama sırrı üretir, gelecekteki teslimatların doğrulanabilmesi için her iki tarafa da aynı değeri girer.
- Bağlantının uçtan uca kabul edildiğini doğrulamak için dış platformdan bir test olayı (ör. bir test siparişi) tetikler.
- Bundan sonra, o platformdan gelen her eşleşen olay otomatik olarak gelir — başka bir işlem gerekmez.
Etkinliği Gerçek Zamanlı İzleme
Bir "Son Webhook Etkinliği" görünümü, her olayı geldiği anda listeler — hangi platformdan geldiği, ne zaman ve hâlâ kuyrukta mı, şu anda işleniyor mu, başarıyla bitti mi yoksa tüm tekrar denemelerden sonra başarısız mı oldu. Bu, bir çalışma alanı yöneticisine sunucu günlüklerini kontrol etmesine gerek kalmadan entegrasyon trafiği üzerinde görünürlük sağlar.
Yük Altında Duyarlı Kalma
Yoğun bir çevrimiçi mağaza işleten bir işletme için, bu motor, birkaç dakika içinde yüzlerce sipariş webhook'u üreten yoğun bir satış artışı sırasında bile TotalApp'in geri kalanının — gösterge panelleri, raporlar, diğer her ekran — hızlı hissettirmesini sağlayan şeydir. Webhook trafiği, o anda uygulamayı kullanan herkesle rekabet etmek yerine arka planda düzenli olarak emilir ve işlenir.
Entegrasyon & Webhook Motoru Nereye Uyuyor?
Bu motor, dış veri için giriş noktasıdır — kabul ettiği şey, gerçek alana özgü iş için diğer motorlara devredilir:
| Tüketici | Entegrasyon & Webhook Motoru'nu nasıl kullanıyor |
|---|---|
| Schema & Data Engine | Kabul edilmiş bir webhook'un payload'ı — yeni bir sipariş, güncellenmiş bir ürün — kullanıcı tarafından tasarlanmış bir koleksiyona doğrulanmış bir kayıt olarak yazılabilir; böylece güvenilmez dış veri, bir formu dolduran bir kişininkiyle aynı alan bazlı doğrulamadan her zaman geçer. |
| Matris Ajanı | Bir webhook aracılığıyla gelen serbest metin içerik — yeni bir lead formu gönderimi, bir tedarikçinin güncellenmiş profili — doğrudan bir puanlama değerlendirmesine yönlendirilebilir; böylece dış olaylar, elle girilen içerikle aynı 0-100 puanlama hattını besler. |
| Denetim Ajanı | Yeni yüklenen bir belgeye referans veren bir webhook, o belgeyi elle yüklenen bir dosyanın geçtiği aynı denetim hattına devredebilir. |
| E-ticaret entegrasyonları (Shopify, WooCommerce) | Bağlı mağazalardan gelen sipariş, ürün ve müşteri olayları, TotalApp'in başka herhangi bir yerinde — gösterge panelleri, raporlar veya otomatik iş akışları — görünmeden önce bu motordan geçer. |
Her gerçek zamanlı entegrasyon bu motordan geçmez
Bazı entegrasyonlar bilinçli olarak anında, her zaman canlı davranış için inşa edilmiştir — örneğin, bir olay geldiği anda, hiç kuyruklama gecikmesi olmadan tetiklenmesi gereken bir workflow node'u. Bu entegrasyonlar, tam olarak bu her-zaman-açık gereksinimi için inşa edilmiş farklı, doğrudan teslimat mekanizmasını kullanır. Entegrasyon & Webhook Motoru, çok daha yaygın olan durum içindir: gerçekleştiği anda canlı olarak görülmesi gerekmeden, bir sonraki anda güvenli ve güvenilir şekilde işlenebilen bir olay.