Bu makale, Şirket Ayarları ekranındaki Entegrasyonlar bölümünü anlatır. Bölümde iki kısım vardır: üstte hazır entegrasyonlar için API anahtarı kartları, altta Webhook'lar (Giden Bildirimler). Webhook listesini Şirket Ayarları Görüntüleme yetkisi olanlar görür; webhook eklemek, değiştirmek, silmek, test etmek ve yeniden denemek için Şirket Ayarları Sorumluluk Verme yetkisi gerekir.

Başlamadan önce

Şirket Ayarları Sorumluluk Verme yetkiniz olmalı (Sorumluluk Yönetme).
Webhook için olayları alacak sistemin adresini (https ile başlayan hedef URL) hazırlayın.
Agentic Payroll anahtarı için Bordro Yönetici Yetkisi gerekir.

Adım adım

Sol menüden Yapılandırma > Şirket ayarları'na gidin.
Soldaki ayar menüsünde Modüller ve Görünüm grubundan Entegrasyonlar'a tıklayın.

Hazır entegrasyon için API anahtarı alma

Bölümde Hirex ve Agentic Payroll kartları bulunur.

Bağlamak istediğiniz kartta API Key Al'a tıklayın. Anahtar oluşturulur ve bir pencerede gösterilir.
Penceredeki kopyalama simgesine tıklayarak anahtarı kopyalayın ve karşı sistemin entegrasyon ekranına yapıştırın. Agentic Payroll anahtarı hangi şirkete ait olduğunu da belirler; ayrıca şirket bilgisi girmeniz gerekmez.
Daha sonra anahtarı yeniden görmek için kartta API Key Görüntüle'ye tıklayın.

Not: Agentic Payroll anahtarı şirketin bordro verisine erişim sağladığı için yalnız Bordro Yönetici Yetkisi olan kullanıcılar üretebilir. Yeni bir anahtar ürettiğinizde, aynı entegrasyon için daha önce sizin ürettiğiniz anahtar silinir.

PDKS cihazları ve harici geçiş sistemleri için kullanılan API anahtarları bu ekranda değil, PDKS modülünün ayarlarında yönetilir (PDKS'ye genel bakış).

Webhook tanımlama

Webhook, Teamso'daki bir olay gerçekleştiğinde sizin belirlediğiniz adrese anlık istek gönderir. Desteklenen olaylar:

Olay	Ne zaman gönderilir
İşe Başlama	Bir çalışan işe başlatıldığında
İşten Ayrılma	Bir çalışanın işten çıkışı yapıldığında
İşten Ayrılma İptali	İşten çıkış iptal edildiğinde
Organizasyon Değişikliği	Çalışanın organizasyon bilgisi değiştiğinde
Rozet verildi	Bir takdir aktif olduğunda: onay gerektirmeyen rozet verildiğinde, onay bekleyen takdir onaylandığında ya da otomatik kural rozet verdiğinde

Webhook'lar (Giden Bildirimler) kısmında Webhook Ekle'ye tıklayın. Yeni Webhook penceresi açılır.
İsim, Hedef URL ve Olaylar alanlarını doldurun. Üçü de zorunludur. Hedef URL http:// ya da https:// ile başlamalıdır (ör. https://ornek.com/webhooks/teamso); www.ornek.com gibi bir adres kabul edilmez.
Aktif anahtarının açık olduğundan emin olun.
Hedef sistem Teamso'nun standart biçimini kabul etmiyorsa Gelişmiş: İstek biçimini özelleştir seçeneğini açın. Burada Yöntem, Gövde biçimi (form alanları ya da JSON), Parametreler ve Gelişmiş ayarlar altında özel başlıklar ile Hata işareti tanımlayabilirsiniz. Değerlere Değişken ekle menüsünden çalışan bilgisini ekleyebilir, Önizle ile örnek çalışan verisiyle oluşacak isteği görebilirsiniz (önizleme istek göndermez; olaylarda yalnız Rozet verildi seçiliyse örnek rozet verisi kullanılır). Bu seçenek yazılım ekipleri içindir.
Değişkenler çift süslü parantez içinde yazılır; filtreler dikey çizgiyle zincirlenir ve soldan sağa uygulanır: {{ değişken | filtre | filtre }}.
- trim: Baştaki ve sondaki boşlukları siler
- lower / upper: Küçük / büyük harfe çevirir (Türkçe kurallarla)
- ascii: Türkçe karakterleri sadeleştirir (ş → s, ı → i)
- initial: Yalnız ilk harf
- first / last: İlk / son kelime; split sonrasında ilk / son parça
- nospace: Tüm boşlukları siler
- alnum: Harf ve rakam dışındaki karakterleri siler
- date: Tarihin yalnız gün kısmı (yyyy-AA-gg)
- split:'ayraç': Metni tırnak içindeki ayraçtan parçalara böler
Örnekler: {{ email | split:'@' | first | lower }} e-postanın @ öncesini verir ([email protected] → ayse.yilmaz); bu ifade Değişken ekle > Hazır ifadeler altında Kullanıcı adı (e-postanın @ öncesi) olarak da bulunur. {{firstName|initial|lower|ascii}}{{lastName|nospace|lower|ascii}} ad baş harfi ve soyaddan kullanıcı adı üretir (Ayşe Yılmaz → ayilmaz).
Organizasyon Değişikliği olayı (pozisyon, departman, yönetici, şube ya da özel alan değişikliği) her seferinde çalışanın tüm organizasyon bilgisini taşır: {{branch}}, {{department}}, {{position}}, {{manager}} güncel değerle gelir; old…/new… çiftlerinde değişmeyen alanın eski ve yeni değeri aynıdır. Böylece hedef sisteme her olayda tüm alanları yazabilirsiniz, değişmeyen alan boş gitmez. Yalnız yönetici değiştiğinde de olay gönderilir.
Kaydet'e tıklayın.

Yeni bir webhook'u kaydettiğinizde Webhook Secret penceresi açılır. Bu anahtar yalnızca bir kez gösterilir; kopyalayıp güvenli bir yerde saklayın. Her isteğin gövdesi bu anahtarla HMAC-SHA256 ile imzalanır ve imza X-Teamso-Signature başlığında gönderilir; karşı sistem bu imzayla isteğin Teamso'dan geldiğini doğrular.

Rozet verildi olayı

Rozet verildi olayı, Performans modülünde bir takdir aktif olduğunda gönderilir. Onay bekleyen, reddedilen ya da geri alınan takdir için olay gönderilmez. Bir kerede birden çok kişiye verilen rozette her kişi için ayrı olay gelir.

Olayda kişiler yalnız kimlik (userId, awardedById) ve görünen adla (fullName, awardedBy) yer alır; rozeti alanın şube, departman ve pozisyon adı da gelir. E-posta, ad soyad parçaları, TC kimlik numarası, telefon ve özel alanlar gönderilmez. Yalnız kişiye ve yöneticisine görünen ("visibility": "PRIVATE") takdirde mesaj gönderilmez (message boş gelir). Puan, yalnız şirket ayarlarında puanlar gösteriliyorsa gelir.

Alan	Anlamı
`badgeName`, `badgeCategory`, `badgeTier`	Rozetin adı, kategorisi ve seviyesi
`fullName`, `branch`, `department`, `position`	Rozeti alan kişi
`awardedBy`	Rozeti veren kişi; otomatik kuralla verilende boş
`source`	Kaynak: `MANUAL` (İK ya da rozet yöneticisi), `MANAGER`, `PEER` (çalışma arkadaşı), `RULE` (otomatik kural), `INTEGRATION` (dış sistem)
`sourceRef`	Dış sistemin gönderdiği olay kimliği (`INTEGRATION:...`) ya da hedef dönemi (`GOAL_PERIOD:...`)
`visibility`, `message`	`PUBLIC` ya da `PRIVATE`; mesaj yalnız `PUBLIC` takdirde
`awardedAt`	Takdirin aktif olduğu an (Türkiye saati)
`silent`	`true`: rozet, otomatik kuralın Geçmişe dönük uygula işleminde bildirim kapalıyken verildi; olay kaydınız için gönderilir, duyurmak için değil

Özel istek biçiminde bu alanlar Değişken ekle menüsünün Rozet grubunda ve {{badgeName}} gibi değişken olarak kullanılır.

Slack ya da Microsoft Teams'e paylaşma: Teamso takdirleri Slack'e ya da Teams'e kendisi göndermez. Webhook'u kendi otomasyon aracınıza (ör. Make, Zapier, n8n ya da Power Automate) bağlayın ve oradan kanalınıza iletin:

Otomasyon aracınızda bir webhook tetikleyicisi oluşturun ve verdiği adresi Teamso'da Hedef URL olarak girin; Olaylar alanında Rozet verildi'yi seçin.
Akışa bir filtre ekleyin: yalnız data.visibility değeri PUBLIC ve data.silent değeri false olan olaylar devam etsin. Böylece yalnız kişiye ve yöneticisine görünen takdirler ve bildirim kapalı geçmişe dönük uygulamada verilen rozetler kanala düşmez.
Slack ya da Teams adımında mesajı olay alanlarından kurun, ör. {{data.fullName}}, {{data.awardedBy}} tarafından "{{data.badgeName}}" rozetiyle takdir edildi: {{data.message}}.

Teamso'nun özel istek biçimiyle doğrudan bir Slack ya da Teams adresine istek göndermek mümkün olsa da bu biçimde olaylar süzülemez; yalnız kişiye ve yöneticisine görünen takdirler de kanala gider. Kanal paylaşımı için süzme yapabilen bir otomasyon aracı kullanın.

Test etme ve teslimatları izleme

Listede webhook satırındaki işlem menüsünden şunları yapabilirsiniz:

Test Gönder: Hedef adrese örnek veriyle istek gönderir ve sonucu (HTTP kodu) gösterir. Özel istek biçiminde önce Gerçek istek gönderilecek onayı çıkar; hedef sistem bu isteği işleyebilir (ör. test kullanıcısı oluşturabilir).
Teslimat Logu: Gönderilen isteklerin Olay, Durum (Başarılı, Başarısız, Bekliyor), HTTP Kodu, Deneme ve Tarih bilgisini listeler. Başarısız bir teslimatı Yeniden Dene ile tekrar kuyruğa alabilirsiniz. Liste uzunsa pencerenin altındaki sayfalamayı kullanın; henüz teslimat yoksa pencerede yalnız "Henüz teslimat kaydı yok." notu görünür.
Düzenle ve Sil: Silinen webhook'un adresine artık bildirim gönderilmez.

Sonuç

Aktif webhook'lar, seçtiğiniz olaylar gerçekleştiğinde hedef adrese otomatik istek gönderir. Teslimatların sonucunu Teslimat Logu'ndan izlersiniz.

Sık karşılaşılan sorunlar

Belirti: Kaydederken "İsim, hedef URL ve en az bir olay zorunludur." uyarısı çıkıyor.
Neden: Zorunlu alanlardan biri boş.
Çözüm: Üç alanı da doldurup tekrar kaydedin.

Belirti: Kaydederken "Hedef URL http:// ya da https:// ile başlamalı" uyarısı çıkıyor.
Neden: Adres www.ornek.com ya da http//:ornek.com gibi eksik veya hatalı yazılmış.
Çözüm: Adresi https:// ile başlayacak şekilde tam yazın (ör. https://ornek.com/webhooks/teamso).

Belirti: Kaydederken "Template error ... Unknown filter" hatası çıkıyor.
Neden: Şablonda listede olmayan bir filtre ya da yanlış yazılmış bir argüman var (ör. split ayraçsız ya da tırnaksız).
Çözüm: Yukarıdaki filtre tablosundaki adları kullanın; split ayracını tırnak içinde yazın: split:'@'.

Belirti: Teslimat logunda kayıtlar Başarısız görünüyor.
Neden: Hedef sistem hata kodu döndürüyor, erişilemiyor ya da yanıt gövdesi Hata işareti metnini içeriyor.
Çözüm: Satırdaki ayrıntıdan yanıtı inceleyin, hedef sistemi düzeltip Yeniden Dene'ye tıklayın.

Belirti: Webhook Ekle düğmesi yok, satır menüsünde yalnız Teslimat Logu var, Aktif anahtarı kilitli ve bölümde "Bu ayarı görüntüleyebilirsiniz ancak düzenlemek için yetkiniz bulunmuyor." yazıyor.
Neden: Şirket Ayarları Görüntüleme yetkiniz var ama Şirket Ayarları Sorumluluk Verme yetkiniz yok. Webhook'ları ve teslimatlarını görebilirsiniz; ekleyemez, değiştiremez, silemez, test edemez ve yeniden deneyemezsiniz.
Çözüm: Şirket yöneticinizden Şirket Ayarları Sorumluluk Verme yetkisini isteyin (Sorumluluk Yönetme).

Belirti: Webhook secret'ını kaybettim.
Neden: Secret yalnız oluşturulduğu anda gösterilir.
Çözüm: Webhook'u silip yeniden oluşturun ve yeni secret'ı karşı sisteme girin.

Belirti: Agentic Payroll kartında API Key Al yerine "API anahtarını bordro yöneticisi alabilir." yazıyor.
Neden: Bordro Yönetici Yetkisi yok; düğme yalnız bu yetkiye sahip kullanıcılara görünür.
Çözüm: Yetkiyi bordro modülünde aldıktan sonra tekrar deneyin (Sorumluluk Yönetme).

Entegrasyonlar ve webhook'lar (API anahtarı, giden bildirimler)