Webhook tetikleyicisi

Genel bakış

Webhook tetikleyicisi, harici sistemlerin iş akışınızı başlatmak için çağırabileceği benzersiz bir HTTP uç noktası sağlar. ajan İş akışları ile HTTP isteği gönderebilen herhangi bir harici hizmet veya uygulama arasındaki köprüdür.

En uygun olduğu durum: Gerçek zamanlı entegrasyonlar, harici sistem olayları, API odaklı iş akışları ve yerel entegrasyonu olmayan hizmetleri bağlama.

Webhook tetikleyicisini ne zaman kullanmalı?

İdeal olduğu durumlar:

• Harici hizmetlerden olay alma (GitHub, Stripe, özel uygulamalar)
• Harici sistemlerden gerçek zamanlı veri işleme
• Özel entegrasyonlar oluşturma
• Webhook destekleyen hizmetleri bağlama (diğer iş akışları dahil)
• Diğer sistemler tarafından başlatılan API odaklı iş akışları

İdeal olmadığı durumlar:

• Kullanıcıya dönük veri toplama (Form tetikleyicisi kullanın)
• Zamanlanmış yinelenen görevler (Zamanlanmış tetikleyici kullanın)
• Yerel entegrasyon olayları (Entegrasyon tetikleyicisi kullanın)

Yapılandırma

Temel kurulum

Bir Webhook tetikleyicisi eklediğinizde otomatik olarak şunları alırsınız:

• Benzersiz webhook URL’si: İstekleri almak için güvenli bir uç nokta
• Webhook kimliği: Webhook’unuz için tanımlayıcı

Güvenlik seçenekleri

Webhook’unuzun nasıl güvence altına alınacağını kontrol etmek için Kimlik doğrulama yöntemi ayarını kullanın. Bir kimlik doğrulama yöntemi seçtiğinizde sizin için otomatik bir gizli anahtar üretilir. Yöntemler arasında geçiş yaptığınızda gizli anahtar korunur; böylece yapılandırılmış anahtarınızı yanlışlıkla kaybetmezsiniz.

Bir kimlik doğrulama yöntemi seçildiğinde gizli anahtar zorunludur. Kimlik doğrulama yöntemi etkinken gizli anahtar alanını boş bırakmak bir doğrulama uyarısı gösterir.

En iyi uygulama: Yetkisiz erişimi önlemek için üretim webhook’larında her zaman bir gizli anahtar kullanın. Gizli anahtarları sunucu günlüklerinden ve tarayıcı geçmişinden uzak tuttuğu için başlık tabanlı kimlik doğrulama tercih edilir.

Sorgu parametresi gizli anahtarı kullanan mevcut webhook’lar değişiklik olmadan çalışmaya devam eder. Kimlik doğrulama yöntemi alanı isteğe bağlıdır — ayarlanmamışsa eski davranış otomatik korunur.

Gelişmiş seçenekler

İş akışında imza başlıklarına veya orijinal istek gövdesine ihtiyacınız olduğunda Gelişmiş seçenekler’de ilgili seçeneği açın. Her iki seçenek de varsayılan olarak kapalıdır.

• İmza başlıklarını dahil et: İstek içerik türünü ve desteklenen imza başlıklarını tetikleyici çıktısına headers altında ekler. Diğer gelen başlıklar çıktıdan çıkarılır. Buna Stripe, GitHub, Slack, DocuSign, Shopify, Svix ve Standard Webhooks imza başlıkları dahildir.
• Ham istek gövdesini koru: Orijinal ayrıştırılmamış gövdeyi tetikleyici çıktısında rawBody altında tutar. Bu seçeneği kullanan istekler, hem ayrıştırılmış hem de ham gövde tutulduğu için 12 MB ile sınırlıdır.

Sonraki bir adımın Stripe gibi bir sağlayıcı imzasını kontrol etmesi gerektiğinde her ikisini de açın.

Nasıl çalışır?

1. Harici sistem webhook URL’sine HTTP POST isteği gönderir
2. Webhook gizli anahtarı doğrular (yapılandırılmışsa, X-Webhook-Secret başlığı veya ?secret= sorgu parametresiyle)
3. İstek yükü ayrıştırılır (JSON gövde ve sorgu parametreleri). Ham istek gövdesini koru açıkken de ayrıştırma devam eder. İmza başlıklarını dahil et açıkken içerik türü ve desteklenen imza başlıkları da tetikleyici çıktısında kullanılabilir.
4. İş akışı yürütme için kuyruğa alınır
5. Webhook hemen 202 Accepted ile yanıt verir
6. İş akışı arka planda asenkron işlenir

headers ve rawBody yalnızca o webhook tetikleyicisinde ilgili anahtar açıksa tetikleyici çıktısında görünür.

Webhook’lar her zaman asenkron işler. Webhook hemen 202 Accepted ile yanıt verirken iş akışı arka planda çalışır.

Webhook’unuza istek gönderme

Temel istek

# No authentication
curl -X POST https://app.ajan.com/api/hooks/workflows/YOUR_WORKFLOW_ID \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# Header authentication (recommended)
curl -X POST https://app.ajan.com/api/hooks/workflows/YOUR_WORKFLOW_ID \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_SECRET" \
  -d '{"key": "value"}'

# Query parameter authentication (legacy)
curl -X POST "https://app.ajan.com/api/hooks/workflows/YOUR_WORKFLOW_ID?secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Dosya gönderme

Webhook dosyalarını tek dosya için file, en fazla 20 dosya için files altında JSON olarak gönderin. Bu anahtarları üst düzeyde veya iç içe nesnelerde kullanabilirsiniz.

Her dosya nesnesi fileName, mimeType ve bir içerik alanı gerektirir. XLSX gibi ikili dosyalar için base64, metin dosyaları için text kullanın. Base64 kodlanmış içerik dahil tam JSON istek gövdesini 25 MB’ın altında tutun. Ham istek gövdesini koru açıkken istek 12 MB ile sınırlıdır.

{
  "files": [
    {
      "fileName": "quarterly-report.xlsx",
      "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "base64": "UEsDB..."
    }
  ]
}

Örnek kullanım senaryoları

GitHub webhook entegrasyonu

Webhook Trigger (GitHub push events)
→ Agent: Analyze commit messages
→ Condition: Check if documentation updated
  → Yes: Regenerate docs
  → No: Continue
→ Notification: Send deployment status

GitHub webhook yapılandırması:

• URL: Webhook URL’niz
• Olaylar: Push, Pull Request
• İçerik türü: application/json

x-hub-signature-256 almak için ajan webhook tetikleyicisinde İmza başlıklarını dahil et’i açın.

Stripe ödeme webhook’u

Webhook Trigger (Stripe events)
→ Code: Validate Stripe signature
→ Condition: Check event type
  → payment_succeeded: Update user account
  → payment_failed: Send retry notification
  → subscription_canceled: Deactivate access

Kod adımının trigger.output.headers içinden stripe-signature ve trigger.output.rawBody içinden orijinal gövdeyi okuyabilmesi için İmza başlıklarını dahil et ve Ham istek gövdesini koru’yu açın.

Özel uygulama entegrasyonu

Webhook Trigger
→ Code: Validate and transform data
→ HTTP Request: Enrich data from external API
→ Agent: Analyze and categorize
→ Action: Create record in CRM

Slack komut entegrasyonu

Webhook Trigger (from Slack slash command)
→ Agent: Process natural language command
→ HTTP Request: Execute action in external system
→ HTTP Response: Send result back to Slack

x-slack-signature ve x-slack-request-timestamp almak için İmza başlıklarını dahil et’i açın.

Webhook verisine erişme

Webhook verisi body (JSON yük) ve query (URL parametreleri) olarak ayrılır. İlgili Gelişmiş seçenekler anahtarı açıksa çıktı ayrıca headers ve/veya rawBody içerir.

İstek gövdesi

JSON yük alanlarına erişin:

{{trigger.output.body.user_id}}
{{trigger.output.body.event_type}}
{{trigger.output.body.data.amount}}

Dosyalar

İşlenen dosyalar istek gövdesindeki orijinal dosya nesnelerinin yerini alır. files altında gönderilen dosyalara trigger.output.body.files içinde erişin:

{{trigger.output.body.files[0].path}}
{{trigger.output.body.files[0]._metadata.name}}
{{trigger.output.body.files[0]._metadata.mimeType}}

file altında gönderilen bir dosya için {{trigger.output.body.file.path}} kullanın.

Sorgu parametreleri

URL sorgu parametrelerine erişin:

{{trigger.output.query.param_name}}

Başlıklar

İmza başlıklarını dahil et açıkken istek içerik türüne ve desteklenen imza başlıklarına erişin:

{{trigger.output.headers["content-type"]}}
{{trigger.output.headers["stripe-signature"]}}

Çıktıdaki başlık adları küçük harftir; örneğin content-type ve stripe-signature. Desteklenmeyen adlar görünmez.

Ham gövde

Ham istek gövdesini koru açıkken orijinal ayrıştırılmamış gövdeye dize olarak erişin. GET istekleri rawBody’yi boş dize olarak ayarlar.

{{trigger.output.rawBody}}

Örnek

Şöyle bir istek için:

POST /api/hooks/workflows/abc123?source=github
Body: {"event": "push", "repo": "my-repo"}

Veriye erişin:

Source: {{trigger.output.query.source}}
Event: {{trigger.output.body.event}}
Repo: {{trigger.output.body.repo}}

Yanıt kodları

Sonraki adımlar

• Entegrasyon tetikleyicisi — Yerel entegrasyon olaylarını kullanın
• HTTP isteği düğümü — Harici API’lere istek yapın
• Kod düğümü — Webhook verisini doğrulayın ve dönüştürün
• Başlarken — İlk iş akışınızı oluşturun

SSS

Harici bir hizmetin HTTP isteği göndererek bir iş akışını başlatması gerektiğinde Webhook tetikleyicisi kullanın. Harici hizmeti, beklenen yöntem, başlıklar ve yükle iş akışının webhook URL’sini çağıracak şekilde yapılandırın.

Webhook URL’sini, istek yöntemini, kimlik doğrulama veya imzalama gereksinimlerini, yük şeklini ve harici hizmetin gerçekten istek gönderip göndermediğini kontrol edin. Ayrıca iş akışının etkin olduğunu ve gelen yükte zorunlu alanların bulunduğunu doğrulayın.