Echobell
App Store Google Play

Webhook Entegrasyonu - HTTP Tetikleyicileri için Eksiksiz Kılavuz

Echobell webhook'larını entegre edin: HTTP yöntemleri, değişkenler, şablonlar, başlıklar ve anında mobil uyarılar için gerçek örnekler.

Webhook'lar, Echobell bildirimlerini tetiklemenin en çok yönlü yoludur. Bu kapsamlı kılavuz, temel kavramlardan gelişmiş kullanım desenlerine kadar webhook tabanlı uyarıları sistemlerinize entegre etmek için bilmeniz gereken her şeyi ele alır.

Webhook nedir

Webhook, bir uygulamanın HTTP geri çağrıları aracılığıyla diğer uygulamalara gerçek zamanlı bilgi sağlamasının bir yoludur. Bunu birine verdiğiniz bir telefon numarası gibi düşünün: o numarayı aradıklarında telefonunuz çalar. Dijital dünyada, bir sistemde bir şey olduğunda (yüksek CPU kullanımı, başarısız bir derleme veya yeni bir sipariş gibi), sistem sizin verdiğiniz bir URL'ye (webhook'a) HTTP isteği gönderir ve bu da sisteminizde bir eylemi tetikler.

Örneğin sunucunuzun CPU kullanımı fazla yükseldiğinde izleme sisteminiz Echobell'in webhook URL'sini çağırabilir; bu da sizi uyarmak için bir bildirim tetikler. Bunların hepsi, siz CPU kullanımını sürekli kontrol etmek zorunda kalmadan, otomatik ve gerçek zamanlı olarak gerçekleşir.

Webhook'lar olay güdümlü mimarilerin temelidir ve neredeyse tüm modern bulut servisleri, izleme araçları ve SaaS platformları tarafından desteklenir. Hafif ve hızlıdırlar; sizin tarafınızda özel bir altyapı gerektirmezler, yalnızca bir HTTP istemcisi yeterlidir.

Webhook'ların Avantajları

  • Gerçek zamanlı: Olaylar bildirimleri anında, genellikle 1-2 saniye içinde tetikler
  • Evrensel: Hemen her modern servis ve programlama dili tarafından desteklenir
  • Esnek: Zengin ve bağlamsal bildirimler oluşturmak için özel veri aktarın
  • Güvenilir: HTTP tabanlıdır; standart durum kodları ve hata işleme sunar
  • Ölçeklenebilir: Yoklama gerekmez; bildirimler yalnızca olaylar gerçekleştiğinde gönderilir

Genel Bakış

Her Echobell kanalı benzersiz bir webhook URL'siyle yapılandırılabilir. Bu URL çağrıldığında kanal, yapılandırılmış bildirim şablonlarına ve sağlanan değişkenlere göre tüm abonelerine bildirim gönderir.

Webhook URL Biçimi

https://hook.echobell.one/t/{channel-token}

Kanalınızın webhook URL'sini Echobell uygulamasındaki kanal ayrıntıları görünümünde bulabilirsiniz.

Webhook İstekleri Gönderme

Echobell webhook'ları hem GET hem de POST yöntemlerini destekler:

GET İsteği

Değişkenleri sorgu parametreleriyle aktarabilirsiniz:

GET https://hook.echobell.one/t/<channel-token>?server_name=Production&cpu_usage=95

POST İsteği

POST istekleri için değişkenleri bir JSON gövdesinde gönderin:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95
}

POST Only

Echobell uygulamasında her kanalın Gelişmiş Ayarlar altında bir POST Only anahtarı bulunur. Varsayılan olarak kapalıdır.

Açık olduğunda kanalı yalnızca POST tetikleyebilir. Webhook URL'sine yapılan bir GET isteği 405 Method Not Allowed ile reddedilir ve hiçbir bildirim gönderilmez:

{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}

HEAD istekleri bundan etkilenmez; POST Only açık da kapalı da olsa 200 yanıtı verir ve asla bildirim tetiklemez.

Webhook URL'si bağlantıları otomatik olarak getiren bir yere düşerse (bir sohbet mesajı, bir wiki sayfası, bir tarayıcı adres çubuğu) bu ayarı açın; böylece URL'nin önizlenmesi veya açılması bir uyarı tetikleyemez. Çağıranlarınızdan herhangi biri kanalı GET ile tetikliyorsa kapalı bırakın.

Özel Değişkenler

Echobell, bildirimlerinize işlevsellik katan özel bir değişkeni destekler:

  • externalLink: İsteğe eklendiğinde, bildirim kayıtları görünümünde tıklanabilir bir bağlantı oluşturur. Ayrıntılı bilgilere veya ilgili kaynaklara bağlantı vermek için kullanışlıdır.

Harici bağlantılı örnek:

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "server_name": "Production",
  "cpu_usage": 95,
  "externalLink": "https://dashboard.example.com/alerts/123"
}

Şablon Değişkenleri

Webhook'lar aracılığıyla aktarılan değişkenler, bildirim şablonlarınızda {{variableName}} sözdizimiyle kullanılabilir:

Title: Server {{server_name}} Alert
Body: CPU usage has reached {{cpu_usage}}%

Tetiklendiğinde bu şablonlar, webhook isteğinizde sağlanan değerlerle doldurulur.

Sistem Zamanı Değişkenleri (UTC)

Gönderdiğiniz verilere ek olarak Echobell, şablonlarda ve koşullarda her zaman kullanılabilen salt okunur sistem zamanı değişkenleri sağlar. Tüm değerler UTC olarak hesaplanır. Düz alanlar şunlardır: date, time, year, month, dayOfWeek, hour, minute ve second. Diğerleri — sys.dayOfWeekName, sys.epochMs ve sys.epochSeconds gibi — yalnızca sys. ad alanı altında kullanılabilir. Tam liste ve örnekler için Koşullar sayfasına bakın.

Yaygın Kullanım Senaryoları

Webhook'lar Echobell'deki en popüler tetikleme yöntemidir ve özellikle şunlar için kullanışlıdır:

DevOps ve İzleme

  • Sunucu İzleme: Prometheus veya Grafana gibi izleme sistemlerinden CPU, bellek ve disk kullanımı uyarıları
  • Erişilebilirlik İzleme: Uptime Kuma veya UptimeRobot üzerinden web sitesi ve servis erişilebilirliği uyarıları
  • Konteyner İzleme: Docker, Kubernetes pod hataları ve kaynak kısıtları
  • Günlük Toplama: Günlük yönetim sistemlerinden kritik hatalar ve istisnalar

Geliştirme ve CI/CD

  • Derleme Bildirimleri: GitHub Actions veya GitLab CI üzerinden başarısız derlemeler, test sonuçları, dağıtım durumu
  • Kod Kalitesi: Lint hataları, güvenlik açıkları, kod kapsamı değişiklikleri
  • Depo Olayları: Pull request'ler, commit'ler, sürümler ve katkıda bulunan etkinlikleri
  • Dağıtım Takibi: Başarılı dağıtımlar, geri alma işlemleri ve ortam değişiklikleri

İş Uygulamaları

  • E-ticaret: Yeni siparişler, ödeme onayları, stok uyarıları, kargo güncellemeleri
  • CRM: Yeni potansiyel müşteriler, kapanan anlaşmalar, destek talepleri, müşteri etkileşimleri
  • Ödeme İşleme: Tamamlanan işlemler, iade talepleri, dolandırıcılık uyarıları
  • Form Gönderimleri: İletişim formları, anket yanıtları, tamamlanan kayıtlar

IoT ve Akıllı Ev

  • Akıllı Ev Olayları: Home Assistant üzerinden kapı sensörleri, hareket algılama, sıcaklık değişimleri
  • IoT Cihazları: Sensör okumaları, cihaz durumu değişiklikleri, bağlantı sorunları
  • Güvenlik Sistemleri: Alarm tetiklemeleri, kamera hareket algılama, geçiş kontrolü olayları
  • Ortam İzleme: Sıcaklık, nem ve hava kalitesi eşiklerinin aşılması

Trading ve Finans

  • Piyasa Uyarıları: TradingView üzerinden fiyat hareketleri, teknik göstergeler
  • Portföy İzleme: Pozisyon değişiklikleri, teminat tamamlama çağrıları, hesap bakiyeleri
  • Ekonomik Olaylar: Haber duyuruları, bilanço raporları, piyasa duyarlılığındaki değişimler

Popüler platformlara özgü kurulum talimatları için entegrasyon kılavuzlarımıza bakın.

En İyi Uygulamalar

Hata İşleme

Yalnızca HTTP durumuna güvenmeyin; her zaman JSON yanıt gövdesini inceleyin ve success alanını kontrol edin:

  • 200 OK: İstek alındı. JSON gövdesini kontrol edin: success: true kanalın tetiklendiği anlamına gelir; success: false ise isteğin kabul edildiğini ancak bildirim gönderilmediğini gösterir (örneğin bilinmeyen bir kanal token'ı, ki bu da yine HTTP 200 döndürür).
  • 400 Bad Request: Kanal token'ının uzunluğu yanlış. Webhook URL'sini düzeltin.
  • 405 Method Not Allowed: Kanalda POST Only açık ve istek POST değildi. Çağıranı POST kullanacak şekilde değiştirin ya da ayarı kapatın.
  • 500 Server Error: Geçici bir sorun; üstel geri çekilme ile yeniden deneyin

Echobell webhook çağrılarına hız sınırı uygulamaz, bu nedenle 429 yanıtı yoktur. Bilinmeyen (ancak uzunluğu geçerli) bir token da success: false ile 200 döndürdüğünden, her zaman HTTP durumuna değil JSON'daki success alanına göre dallanın.

Hız Sınırlaması

Bildirim sisteminizi boğmamak için webhook çağrıları arasında makul gecikmeler uygulayın:

  • Sürekli izleme için birden çok olayı tek bir bildirimde toplayın
  • Kritik olmayan olayları elemek için koşulları kullanın
  • Arka arkaya gelen olayları (örneğin kısa sürede oluşan çok sayıda hata) toplulaştırmayı değerlendirin
  • Kritik uyarıların güvenilir kalması için arka arkaya yinelenen tetiklemeler göndermekten kaçının

Veri Güvenliği

Webhook URL'lerini yalnızca güvendiğiniz sistem ve servislerle paylaşın:

  • Webhook URL'lerini birer sır olarak değerlendirin; bildirim gönderme yetkisine doğrudan erişim sağlarlar
  • Webhook URL'lerini herkese açık depolara göndermeyin veya herkese açık belgelerde paylaşmayın
  • Webhook URL'lerini düzenli aralıklarla ya da ekip üyeleri ayrıldığında yenileyin
  • Ele geçirilmişse eski URL'leri geçersiz kılmak için kanalın "Token'ı Sıfırla" özelliğini kullanın
  • URL'leri saklamak için ortam değişkenlerini veya sır yönetim sistemlerini kullanmayı değerlendirin

Değişken Adlandırma

Webhook çağrılarınızda açık ve tutarlı değişken adları kullanın:

  • Açıklayıcı adlar kullanın: s veya srv yerine server_name
  • Kanallar arasında tutarlı bir adlandırma kuralına uyun
  • Şablonlarınızın hangi değişkenleri beklediğini belgeleyin
  • Göndermeden önce tüm gerekli değişkenlerin bulunduğunu doğrulayın

Test Etme

Üretime almadan önce webhook entegrasyonunuzu iyice test edin:

  1. İlk testler için curl, Postman veya dilinizin HTTP istemcisi gibi araçları kullanın
  2. Basit şablonlarla başlayın ve karmaşıklığı kademeli olarak artırın
  3. En iyi sonucu bulmak için hem GET hem de POST yöntemlerini deneyin
  4. Özel karakterlerin ve Unicode'un doğru işlendiğini doğrulayın
  5. Davranışı anlamak için hata senaryolarını (eksik değişkenler, bozuk JSON) test edin
  6. Geliştirme sırasında üretim kanallarından ayrı test kanalları kullanın

Şablon Tasarımı

İsteğe bağlı değişkenler eksik olduğunda bile kullanışlı kalan şablonlar tasarlayın:

  • İsteğe bağlı veriler için varsayılan değerler veya yedekler sağlayın
  • Şablonları eksik değişkenleri sorunsuz karşılayacak şekilde kurgulayın
  • Şablonları, var olan ve olmayan değişkenlerin çeşitli birleşimleriyle test edin
  • İsteğe bağlı bölümler için koşullu ifadeleri kullanın

İzleme

Webhook entegrasyonlarınızın doğru çalıştığından emin olmak için onları izleyin:

  • Başarılı ve başarısız webhook çağrılarını uygulamanızda günlüğe kaydedin
  • Bildirim teslim oranlarını ve yanıt sürelerini takip edin
  • Webhook hataları veya olağan dışı desenler için uyarılar kurun
  • Kritik webhook entegrasyonlarını düzenli olarak gözden geçirin ve test edin

Gizlilik ve Güvenlik

Echobell'in webhook verilerinizi nasıl işlediğini anlayın:

Nelerin Saklandığı

  • Sunucularımızda:

    • Webhook URL'leri (token'lar) - gelen istekleri kanallara yönlendirmek için gereklidir
    • Kanal yapılandırmaları - şablonlar, koşullar, ayarlar
    • Abonelik ilişkileri - hangi kullanıcıların hangi kanallara abone olduğu

  • Cihazınızda:

    • Bildirim içeriği - işlenmiş başlık ve gövde metni
    • Tetikleme geçmişi - bildirimlerin ne zaman alındığı
    • Değişken değerleri - webhook çağrılarında aktarılan veriler
    • Bağlantılar ve meta veriler - externalLink ve diğer ilişkili veriler

Nelerin Saklanmadığı

  • Ham webhook yüklerini kalıcı olarak saklamayız
  • İsteklerinizdeki hassas verileri günlüğe kaydetmez veya tutmayız
  • Bildirim içeriğini hiçbir amaçla analiz etmez ya da işlemeyiz
  • Webhook verilerinizi üçüncü taraflarla paylaşmayız

Güvenlik Önerileri

  • Webhook URL'lerini API anahtarı gibi değerlendirin - bildirim göndermek için kimlik doğrulaması gerektirmeyen erişim sağlarlar
  • URL'leri düzenli olarak yenileyin - yeni URL'ler üretmek için "Token'ı Sıfırla" özelliğini kullanın
  • HTTPS istemcileri kullanın - yalnızca HTTPS bağlantılarını kabul etsek de istemcinizin sertifikaları doğruladığından emin olun
  • Webhook kaynaklarını doğrulayın - mümkünse webhook'larınızı hangi IP'lerin veya servislerin çağırabileceğini kısıtlayın
  • Kötüye kullanımı izleyin - olağan dışı desenleri veya yetkisiz kullanımı takip edin
  • Ortamları ayırın - geliştirme, hazırlık ve üretim için farklı kanallar kullanın

Daha fazlasını destek dokümantasyonumuzda öğrenin.

Sorun Giderme

Webhook'larınız beklendiği gibi çalışmıyorsa bu tanılama adımlarını deneyin:

Webhook Bildirim Tetiklemiyor

  1. Webhook URL'sinin doğru olduğunu doğrulayın

    • URL'yi doğrudan Echobell uygulamasından kopyalayın
    • Fazladan boşluk veya karakter eklenmediğinden emin olun
    • Başka bir alan adı değil, https://hook.echobell.one/t/ kullandığınızı kontrol edin

  2. Kanalın etkin olup olmadığını kontrol edin

    • Kanalı Echobell uygulamasında açın
    • Silinmediğini veya arşivlenmediğini doğrulayın
    • Webhook token'ını sıfırlamadığınızdan (bu URL'yi geçersiz kılar) emin olun

  3. JSON yükünüzün doğru biçimlendirildiğinden emin olun (POST istekleri için)

    • Yükünüzü kontrol etmek için bir JSON doğrulayıcı kullanın
    • Metinlerin doğru tırnak işaretleri içinde olduğundan emin olun
    • Content-Type başlığının application/json olarak ayarlandığını doğrulayın

  4. Şablonlarınızdaki tüm gerekli değişkenlerin sağlandığını onaylayın

    • Hangi değişkenleri kullandıklarını görmek için bildirim şablonlarınızı kontrol edin
    • Bu değişkenlerin webhook isteğinizde (sorgu parametreleri veya JSON gövdesi) yer aldığını doğrulayın
    • Eksik değişkenlerin boş metin olarak işleneceğini unutmayın

  5. Kanalın etkin abonesi olup olmadığını kontrol edin

    • Bildirimler yalnızca kanala abone olan biri varsa gönderilir
    • Uygulamanın kanal listesinde aboneliğinizi doğrulayın
    • Aboneliklerin yanlışlıkla kaldırılmadığını kontrol edin

Bildirimler Yanlış Görüntüleniyor

  1. Değişken adları eşleşmiyor

    • Şablon {{server_name}} kullanıyor ama webhook serverName gönderiyor
    • Değişken adları büyük/küçük harfe duyarlıdır ve tam olarak eşleşmelidir
    • Değişken adlarında yazım hatası olup olmadığını kontrol edin

  2. İç içe verilere erişilemiyor

    • Nokta gösterimini kullanın: {{user.name}} ya da köşeli parantez gösterimini: {{user["name"]}}
    • JSON yapınızın şablon beklentilerinizle örtüştüğünü doğrulayın
    • Önce basit, düz değişkenlerle test edin, sonra iç içe yapı ekleyin

  3. Özel karakterler soruna yol açıyor

    • Sorgu parametrelerini düzgün şekilde URL kodlayın
    • POST gövdelerinde özel JSON karakterlerini kaçış karakteriyle yazın
    • Önce basit ASCII metinle test edin

Entegrasyonunuzu Test Etme

Webhook'unuzu doğrudan test etmek için curl kullanın:

# Test with query parameters
curl "https://hook.echobell.one/t/<channel-token>?test=hello&status=working"

# Test with JSON body
curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H "Content-Type: application/json" \
  -d '{"test": "hello", "status": "working"}'

Her şey doğru yapılandırıldıysa anında bir bildirim almanız gerekir.

Hâlâ Sorun mu Yaşıyorsunuz?

Yukarıdaki adımları denediğiniz halde sorun devam ediyorsa:

  • Daha fazla sorun giderme kılavuzu için Destek Merkezimizi ziyaret edin
  • Bilinen sorunlar veya servis durumu güncellemeleri olup olmadığını kontrol edin
  • Şu bilgilerle echobell@weelone.com adresinden bize ulaşın:
    • Sorunun açıklaması
    • Denediğiniz adımlar
    • Örnek webhook URL'si (token kaldırılmış/gizlenmiş olarak)
    • Örnek istek yükü
    • Beklenen ve gerçekleşen davranış

Sonraki Adımlar

Artık webhook entegrasyonunu anladığınıza göre:

Echobell'i sistemlerinizle entegre etmeye hazır mısınız? İlk kanalınızı oluşturun ve anında bildirim almaya başlayın!