Webhook ve otomasyon

Bu sürümde outbound webhook yok

Açıkça söylemek gerekirse: FlowDesk, talep yaşam döngüsü olaylarında (durum değişti, atandı, tamamlandı…) sizin sisteminize bir webhook/callback göndermez. Bu, plana geç eklenmiş bir kısıtlama değil, mevcut sürümün tasarım kararı. Entegrasyon yüzeyinin resmi kapsam dışı listesinde açıkça yer alır: “webhooks/callbacks (not available in this version, outcomes are learned by polling)”. Kod tarafında da bunu doğrulayan bir şey yok: v1/integration/* ve v1/external/* altında dışarıya istek atan, sizin bir URL’nizi çağıran hiçbir bileşen bulunmuyor.

v1/integration/inbound-email/webhook adında bir endpoint görebilirsiniz: bu, adının aksine sizin sisteminize giden bir webhook değildir; posta sağlayıcınızın (ör. Mailgun) e-postaları FlowDesk’e ilettiği, size hiçbir faydası olmayan gelen bir endpoint’tir (bkz. Kurulum → E-posta ayarları). Talep yaşam döngüsü olayları için sizin dinleyebileceğiniz bir karşılığı yoktur.

Bunun anlamı: sonuçları push ile değil, polling ile öğrenirsiniz. Bu bölümün geri kalanı bunu güvenilir şekilde nasıl yapacağınızı anlatır.

Yaşam döngüsü olaylarını polling ile takip etmek

Elinizdeki araçlar Talep açma sayfasında ayrıntılı anlatılıyor; burada “olaya bağlanma” açısından özetliyoruz:

• Tek bir talebin güncel durumu için: GET /v1/integration/tickets/{id} veya .../by-tracking-key/{trackingKey}. Tekil talep yanıtı her yazımda geçersiz kılınır: yani bu iki endpoint her zaman güncel sonucu verir, gecikmeli değil.
• ETag ile verimli polling: tekil talep yanıtı bir ETag taşır; bir önceki sorgudan aldığınız değeri If-None-Match olarak gönderirseniz, talep değişmediyse gövdesiz bir 304 alırsınız: değişip değişmediğini öğrenmek için tüm gövdeyi tekrar tekrar taşımanız gerekmez.
• Birden çok talebi taramak için: GET /v1/integration/tickets?statusIds=..., ama bu yanıt yalnızca süreyle cache’lenir (varsayılan 45 saniye) ve yazımda geçersiz kılınmaz; bir talebin an be an doğru durumu için değil, toplu tarama için kullanın.

Pratik bir desen: kendi tarafınızda trackingKey başına bir polling zamanlayıcısı tutun (talep açtıktan hemen sonra sık, zamanla seyrekleşen aralıklarla: 1s, 2s, 4s, sonra dakikalar), talep isCompleted/ticketStatusId alanı beklediğiniz duruma geldiğinde ya da kendi iş kurallarınıza göre bir üst sınıra ulaştığında durdurun. 429 aldığınızda Retry-After süresi kadar bekleyip devam edin; bkz. Talep açma → Hata sözleşmesi.

Talebiniz sizin hiçbir eyleminiz olmadan neden değişebilir

Siz v1/integration/tickets ile bir talep açtıktan sonra, o talebin durumu sizin API çağrınız dışındaki nedenlerle değişebilir: bir ajan panelden yanıtlar, bir SLA eskalasyon zinciri talebi üst kademeye devreder, ya da dashboard’da tanımlı bir otomasyon kuralı (iş akışı motoru) devreye girer. Polling yapan bir entegrasyon için pratik sonuç şu: talebinizin durumu, siz hiçbir şey yapmasanız bile değişebilir: bu yüzden “bir kere okudum, bitti” değil, düzenli sorgulama gerekir.

Bu otomasyon motoru dashboard’da bir yönetici tarafından yapılandırılır, entegrasyon API’sinin bir parçası değildir ve sizin token’ınızla ne oluşturulabilir ne de sorgulanabilir. Ne yaptığını bilmeniz, yalnızca talebinizin neden kendiliğinden değiştiğini anlamanıza yardımcı olur:

• Tetikleyiciler: talep oluşturuldu, durumu değişti, atandı, müşteri yanıt verdi, ya da zamanlanmış bir tarama (dakikada bir).
• Koşullar: talebin alanları üzerinde (durum, öncelik, havuz, son müşteri yanıtından bu yana geçen süre, …) AND/OR ile kurulan bir koşul ağacı.
• Aksiyonlar: durum değiştirme, eskalasyon (havuz/kullanıcı devri + öncelik yükseltme), yeniden atama, e-posta gönderme, panel içi bildirim, günlüğe yazma.

Aynı kural, aynı talep üzerinde art arda tetiklenmez: varsayılan 1440 dakikalık (bir gün) bir bastırma penceresi vardır; bu pencere içinde aynı kural sessizce atlanır. Bunu bilmek, “kuralım neden tekrar çalışmadı” sorusuna kendi başınıza cevap bulmanızı sağlar; ayarını değiştirmek istiyorsanız muhatabınız kendi kurumunuzun FlowDesk yöneticisidir, bu API değil.

“Yeniden deneme” burada ne anlama gelir

Push tabanlı bir webhook olmadığı için, klasik “webhook’u X kez yeniden dene” kavramı yok. Sizin tarafınızda dayanıklı bir entegrasyon için önemli olan üç şey:

1. Idempotency-Key ile talep açma çağrılarınızı güvenle tekrarlayabilmek; bkz. Talep açma → Güvenli tekrar deneme.
2. 429 üzerinde Retry-After’a uymak: başarılı yanıtlar rate limit başlığı taşımaz, kalan kotanızı önceden göremezsiniz; geri çekilme kararınızı yalnızca 429 yanıtındaki Retry-After değerine dayandırın.
3. 503 / FD:0011 karşısında geri çekilip tekrar denemek: deployment’ın lisans durumu geçici olarak işlem reddediyorsa bu sizin isteğinizle ilgili değildir; kurumunuzun FlowDesk yöneticisiyle iletişime geçin.

Sırada ne var

• Talep açma ve okuma endpoint’lerinin tam sözleşmesi: Talep açma
• Son kullanıcının kendi talebini kimlik doğrulamadan takip etmesi: Talep takibi
• İki credential’ın neden birbirine karışmadığı: Kimlik doğrulama