Webhook ve API tetikleyicileri

Bu rehberde: İş akışınızı OrqLabs dışından başlatmayı öğrenirsiniz. Web sitenizdeki form, Zapier veya kendi yazılımınız bir adres çağırır; iş akışı çalışır.

⏱ 15 dakika

İki yol#

Webhook tetikleyici#

Kurulum#

1. İş akışınıza paletten Webhook tetikleyicisini ekleyin.
2. Denetçi panelinde alanları doldurun:
   • Method: POST (varsayılan), GET veya PUT.
   • Path suffix: boş bırakın (rastgele, tahmin edilemez bir yol üretilir) veya siparis-formu gibi okunabilir bir yol yazın. Yol organizasyon içinde benzersiz olmalıdır.
   • Shared secret header: paylaşılan gizli anahtar. Doluysa istek X-Webhook-Secret başlığında aynı değeri taşımalıdır.
   • Respond: immediately → hemen 202 ve { runId } döner; lastNode → şu an immediately ile aynı çalışır (202 ve { runId }); sonucu çalıştırma kaydından okursunuz.
3. Kaydet ve Etkinleştir deyin. Adres denetçi panelinde görünür.

Adres kalıbı:

https://api.orqlabs.com/api/v1/hooks/<yol>

İş akışı Etkin değilse adres 404 döner.

Geliştirici notu: Adres {PUBLIC_WEBHOOK_URL}/api/v1/hooks/<webhookPath> kalıbıyla üretilir; yerel geliştirmede PUBLIC_WEBHOOK_URL bir ngrok adresidir. API ile: GET /orgs/:orgId/workflows/:id/webhook-url → { url }.

Gelen veri neye benzer?#

{
  "method": "POST",
  "headers": { "content-type": "application/json", "user-agent": "…" },
  "query": { "source": "site" },
  "body": { "name": "Ayşe Kaya", "email": "ayse@ornek.com", "message": "Fiyat teklifi" },
  "receivedAt": "2026-09-26T08:12:00Z"
}

Form alanlarına {{ $json.body.email }} ile erişirsiniz. Form kodlu gövdeler (application/x-www-form-urlencoded) nesneye çevrilir. Dosyalar (multipart/form-data) binary altında gelir; en fazla 10 MB.

Örnek: site formu → aday → puanlama → bildirim#

Webhook (POST, gizli anahtar "s3cret", hemen yanıtla)
→ Aday oluştur (ad {{ $json.body.name }}, e-posta {{ $json.body.email }}, telefon {{ $json.body.phone }}; kaynak "website")
→ Lead Qualifier (eşik 60)
→ Eğer ({{ $json.score >= 60 }})
   true  → Bildir ("Yeni nitelikli aday: {{ $json.name }}", kanallar [inapp, slack])
   false → Boş işlem

Gönderim:

curl -X POST "https://api.orqlabs.com/api/v1/hooks/siparis-formu" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: s3cret" \
  -d '{"name":"Ayşe Kaya","email":"ayse@ornek.com","phone":"+905551112233"}'
# → 202 {"runId":"run_01J..."}

Sonucu almak (lastNode)#

Respond alanında lastNode seçeneği görünse de şu an istek hemen 202 ve { runId } ile yanıtlanır; akışın bitmesini beklemez. Sonucu almak için dönen runId ile GET /api/v1/orgs/:orgId/runs/:runId isteği yapın ve status alanı SUCCEEDED olduğunda son adımın çıktısını okuyun. Anlık yanıt gereken durumlarda (ör. sitenizdeki sohbet kutusu) web sohbeti uç noktasını kullanın.

Güvenlik#

• Gizli anahtar alanını her zaman doldurun. Boşsa adresin gizliliği tek koruma olur.
• Gönderen IP'yi kısıtlamak için Süz kutusu: {{ ["1.2.3.4"].includes($json.headers["x-forwarded-for"]) }}.
• Hız sınırı: organizasyon başına dakikada 600 istek; aşımda 429.
• Aynı verinin iki kez gelmesine karşı Tekrarları kaldır ({{ $json.body.id }}).
• Stripe, Shopify gibi sağlayıcı imzaları Kod kutusunda doğrulanamaz (kripto kütüphanesi yok). Bu kaynakları önce kendi sunucunuzdan geçirin veya paylaşılan gizli anahtara güvenin.

Form tetikleyici#

Kod yazmadan barındırılan bir form: https://api.orqlabs.com/api/v1/public/forms/<slug>. GET form tanımını verir; POST gönderimi alır. Denetçi panelindeki Embed sekmesi iframe kodunu ve doğrudan bağlantıyı gösterir. UTM parametreleri öğenin utm alanına yazılır. Spam için hız sınırı ve gizli tuzak alanı vardır.

API ile çalıştırma#

curl -X POST "https://api.orqlabs.com/api/v1/orgs/$ORG/workflows/$WF/run" \
  -H "X-Api-Key: af_live_..." -H "Content-Type: application/json" \
  -d '{"input":{"topic":"Kış kampanyası","platforms":["LINKEDIN"]},"testMode":false}'
# → { id, status: "QUEUED", triggerType: "API", ... }

• input tetikleyici kutunun çıktı öğesi olur. Manuel tetikleyici beklenir; başka tetikleyici varsa yine çalışır.
• testMode: true yayın ve mesaj kutularını kuru çalıştırır.
• nodeId ile belirli bir kutudan başlatabilirsiniz; önceki çıktılar son çalıştırmadan alınır.

Sonucu takip etme#

until [ "$(curl -s -H "X-Api-Key: $KEY" https://api.orqlabs.com/api/v1/orgs/$ORG/runs/$RUN | jq -r .status)" != "RUNNING" ]; do sleep 3; done

Tek ajan çalıştırma#

İş akışı olmadan tek ajan: POST /orgs/:orgId/agents/run { type, task, input, projectId, modelId? }. Sonuç için GET /orgs/:orgId/agent-runs/:id. Bkz. Genel API hızlı başlangıç.

Ters yön: OrqLabs'tan dış sisteme#

Webhook gönder kutusu, CRM'e yaz (Webhook hedefi) veya Ayarlar → Webhook'lar altında olay abonelikleri. İmza doğrulama ve olay listesi: Giden webhook'lar.

Sorun giderme#

Sık sorulan sorular#

Zapier ile bağlayabilir miyim? Evet. Zapier'de "Webhooks by Zapier → POST" adımına OrqLabs webhook adresini yapıştırın. Gizli anahtarı başlık olarak ekleyin.

Web sitemdeki formu bağlamak için kod gerekir mi? Form sağlayıcınız (Typeform, Tally, WordPress eklentisi) genellikle "webhook" ayarı sunar; adresi oraya yazmanız yeterlidir. Ya da OrqLabs'ın Form tetikleyicisini kullanın; hazır iframe verir.

Webhook adresi değişir mi? Yol sabittir. Yalnızca siz Path suffix alanını değiştirirseniz değişir.

Aynı adrese saniyede çok istek gelirse? Dakikada 600 istekten sonrası 429 alır. Yüksek hacimde istekleri toplayıp gönderin.

Sonraki adım#

• Tetikleyici node'ları
• Giden webhook'lar
• API anahtarları
• Custom Webhook entegrasyonu