Özel Webhook Tetikleyicisi
Bir Özel Webhook, akışınıza benzersiz bir HTTP URL'si verir. Harici bir sistem bu URL'ye bir istek gönderdiğinde, akış isteğin verilerini girdi olarak kullanarak çalışır. Webhook'lar, AgentFlow'u yerleşik olmayan herhangi bir platforma — özel CRM'ler, form oluşturucular, Telegram botları, e-ticaret mağazaları, dahili araçlar veya HTTP isteği gönderebilen herhangi bir şeye — bağlama şeklinizdir.
Webhook'ları Başlangıç node üzerinde Webhook'lar altında yapılandırırsınız. Eklediğiniz her webhook, kendi URL'sini ve kendi güvenlik ayarlarını alır.
Bir akışa ekleme
Başlangıç node üzerinde Webhook'lar'ı açın, bir webhook ekleyin ve Webhook Türü'yü Özel Webhook olarak ayarlayın. Ardından bir mod ve bir doğrulama yöntemi seçin.
Dedicated ile Çalışma Alanı modu karşılaştırması
İlk seçim Webhook Modu'dur:
| Mod | Ne yapar | Ne zaman kullanılır |
|---|---|---|
| Dedicated | Yalnızca bu akış için benzersiz bir URL oluşturur. Tüm güvenlik ve yük ayarları bu webhook üzerinde yer alır. | Çoğu entegrasyon — bir harici sistem bir akışla konuşur. |
| Çalışma Alanı | Bir URL'yi çalışma alanındaki birkaç akış arasında paylaşır. Gelen istekler akışlara filtreler ile yönlendirilir. | Meta (Instagram/WhatsApp) ve bir uç noktanın birden fazla akışa dağıtım yapması gereken her durum. |
Meta entegrasyonları Çalışma Alanı modunu gerektirir. Instagram ve WhatsApp'ın her ikisi de her olayı tek bir Meta webhook URL'sine iletir; bu nedenle o olayları doğru akışlara yönlendirmek için (filtrelerle) paylaşılan bir çalışma alanı webhook'u gereklidir. Amaca yönelik bir Meta kurulumu için bunun yerine özel Instagram ve WhatsApp tetikleyicilerini tercih edin — her şeyi otomatik olarak yapılandırırlar.
Dedicated modunda bir Webhook Adı (URL'de ve {{$webhook.<name>.*}} değişkenlerinde kullanılır), isteğe bağlı bir Açıklama ve bir Etkin anahtarı ayarlarsınız. Çalışma Alanı modunda mevcut bir çalışma alanı webhook'u seçersiniz (veya yeni bir tane oluşturursunuz) ve Filtreler eklersiniz — her istek, akışı tetiklemek için tüm filtrelerle eşleşmelidir.
Webhook URL'si
Özel bir webhook'un URL'si şu deseni takip eder:
POST /api/v1/webhook/{flowId}/{webhookName}
Harici sistemler buraya bir HTTP POST gönderir. İstek, bir chatId ve sessionId ile hemen geri döner — akış daha sonra arka planda çalışır. Bu "gönder ve unut" davranışı, akışınız düşünmek için saniyelerce sürse bile hızlı zaman aşımına uğrayan platformları memnun tutar.
Doğrulama yöntemleri
Doğrulama (Verification), Flowera'nın gelen bir isteğin gerçekten güvendiğiniz sisteminizden geldiğini, URL'yi tahmin eden bir saldırgandan gelmediğini onaylama şeklidir. Platformunuzun desteklediği yöntemi seçin.
HMAC imzası
Platform, her istek gövdesini paylaşılan bir gizli anahtarla imzalar ve Flowera, eşleştiğini onaylamak için imzayı yeniden hesaplar. GitHub, Meta, Shopify ve Stripe tarafından kullanılır. HMAC SHA-256 (önerilen), SHA-1 (eski) ve SHA-512 olarak mevcuttur.
| Alan | Açıklama |
|---|---|
| HMAC Gizli Anahtarı | Gönderen platform tarafından sağlanan imzalama gizli anahtarı. |
| İmza Başlık Adı | İmzayı taşıyan başlık (örn. GitHub/Meta için x-hub-signature-256, Shopify için x-shopify-hmac-sha256). |
| İmza Ön Eki | İmzadan önce gelen isteğe bağlı metin (örn. GitHub için sha256=). Hiçbiri yoksa boş bırakın. |
JWT token
İmzalanmış bir JSON Web Token'ı doğrular — OAuth tabanlı sistemlerde yaygındır.
| Alan | Açıklama |
|---|---|
| JWT Gizli/Genel Anahtar | İmzalama gizli anahtarı (HS algoritmaları için) veya genel anahtar (RS algoritmaları için). |
| JWT Algoritması | İmzalama algoritması: HS256/384/512 veya RS256/384/512. |
| JWT Token Konumu | Token'ın istekte bulunduğu yer: Header, İstek Gövdesi veya Sorgu Parametresi. |
| JWT Token Alan Adı | Token'ı tutan alan/başlık (örn. authorization). |
Bearer token
Authorization başlığına karşı basit paylaşılan token kontrolü.
| Alan | Açıklama |
|---|---|
| Bearer Token | Beklenen gizli token. |
| Bearer Token Başlık Adı | Token'ı taşıyan başlık (varsayılan authorization). |
Custom header
Belirli bir başlığın beklenen bir değer taşıdığını kontrol eder — örneğin bir X-API-Key.
| Alan | Açıklama |
|---|---|
| Başlık Adı | Kontrol edilecek başlık (örn. x-api-key, x-webhook-token). |
| Beklenen Başlık Değeri | O başlığın içermesi gereken gizli değer. |
Meta Challenge Verification
Meta (Instagram/WhatsApp) ve Slack, bir webhook'u olayları iletmeden önce tek seferlik bir GET challenge göndererek doğrular. Buna yanıt vermek için Doğrulama Sınamasını Etkinleştir'i açın.
| Alan | Açıklama |
|---|---|
| Sınama Parametresi Adı | Challenge değerini taşıyan sorgu parametresi (Meta hub.challenge, Slack challenge kullanır). |
| Doğrulama Token Parametresi Adı | İsteğe bağlı — verify token'ı taşıyan parametre (Meta hub.verify_token kullanır). |
| Doğrulama Token Değeri | Platformun gönderdiğine karşı eşleştirilen, beklenen verify token. |
| Sınama Yanıt Modu | Sınamayı Yansıt challenge değerini döndürür (Meta, Slack); Sabit Yanıt sabit bir dize döndürür. |
| Sabit Yanıt Metni | Yalnızca Sınama Yanıt Modu Sabit Yanıt olduğunda kullanılan sabit yanıt metni. |
Özel platformlar için başka doğrulama yöntemleri de mevcuttur: Temel Kimlik Doğrulama (kullanıcı adı + parola), Sorgu Parametresi (URL'deki bir gizli anahtar) ve ED25519 İmzası (Discord Interactions). Ayrıca bir Yok seçeneği vardır — her isteği hiçbir kontrol olmadan kabul et — ki bu kesinlikle yalnızca yerel test içindir.
Bir üretim webhook'unu asla Yok doğrulamasında bırakmayın ve mümkün olduğunda Sorgu Parametresi'den kaçının — URL'ler (ve sorgu dizeleri) genellikle yol boyunca günlüğe kaydedilir. HMAC veya başlık tabanlı yöntemleri tercih edin.
Yükü akışınızda okuma
Webhook'un Örnek Payload alanına örnek bir istek yapıştırdığınızda, Flowera onun yapısını okur ve her alanı {{$webhook.<name>.<field>}} olarak kullanılabilir hale getirir. { "customer": { "email": "..." } } alan crm adlı bir webhook için {{$webhook.crm.customer.email}} kullanırsınız. Ham gövdenin tamamı {{$webhook.crm.payload.raw}} olarak mevcuttur.
Ayrıca aynı müşteriden gelen tekrar eden isteklerin aynı konuşmaya düşmesi için bir Session ID Şablonu (örn. {{$webhook.crm.senderId}}) ayarlayabilirsiniz. İstek başına yeni bir oturum oluşturmak için boş bırakın. Ayrıntılar için Değişkenler sayfasına bakın.
Test etme
- Canvas test panelinin gerçek bir isteği simüle edebilmesi için webhook üzerine bir Örnek Payload ekleyin — böylece siz oluştururken
{{$webhook.<name>.*}}değişkenleriniz çözümlenir. - Akış devreye alındıktan sonra
curlveya platformunuzun test butonuyla gerçek bir istek gönderin:
curl -X POST https://your-flowera-instance.com/api/v1/webhook/FLOW-ID/crm \
-H "Content-Type: application/json" \
-d '{ "message": "I need help with my order", "senderId": "user-123" }'
İpuçları
- Tek bir Başlangıç node, her biri kendi adı, URL'si ve güvenliğine sahip birden fazla webhook tutabilir — farklı sistemlerden gelen olayları ayırmak için kullanışlıdır.
- Her webhook'a net bir ad verin: URL'de ve her
{{$webhook.<name>.*}}değişkeninde görünür. - Bir müşterinin mesajını sohbet geçmişine yerleştirmek için yük alanını
$question'a eşleyin.