n8n iş akışları

AI-School, n8n iş akışlarını bir üretim webhook’u üzerinden başlatabilir. Bu, AI-School dışında otomatik bir süreci başlatmak istediğinizde kullanışlıdır; örneğin bir görev oluşturmak, bir CRM kaydını güncellemek, bir raporlama akışını başlatmak veya form verilerini başka bir sisteme aktarmak için.

Örnek: okul web sitesinde haber makalesi

Diyelim ki okul, n8n’de okulun WordPress web sitesinde bir haber makalesi yayınlayan bir iş akışı oluşturdu. AI-School’da yalnızca kısa bir metin girersiniz; örneğin bir proje haftası, spor günü veya açık gün hakkında birkaç cümle. Bu metinle iş akışını n8n’de başlatırsınız.

n8n iş akışı daha sonra örneğin şunları yapabilir:

1. Kısa metni, okulun tonuna uygun bir prompt kullanan bir LLM node’u ile düzgün bir taslak metne dönüştürmek.
2. Okulun renklerinde ve tanınabilir bir illüstratif tarzda, ikinci bir LLM node’u ile uygun bir görsel oluşturmak.
3. Metin ve görseli WordPress web sitesinde bir blog yazısı olarak hazırlamak veya yayınlamak.

Böylece AI-School ve n8n birlikte çalışır: AI-School’da kullanıcı iş akışını seçer ve gerekli bilgileri girer. Ardından n8n otomatik adımları yürütür ve haber makalesinin düzgün şekilde web sitesine ulaşmasını sağlar.

Bu entegrasyon ne yapar?

Bir iş akışı özetinden n8n iş akışı başlatırsınız. Yalnızca üretim webhook’u, POST ve Header Auth zorunludur. n8n’den gelen alanlar ve geri bildirimler isteğe bağlıdır ve birbirinden bağımsız olarak yapılandırılabilir.

• İş akışında alan yoksa webhook hemen çağrılır.
• İş akışında alan varsa önce bir form açılır. Kullanıcı alanları doldurur ve ardından düğme ile iş akışını başlatır.
• Girilen değerler, n8n webhook’una bir POST request ile JSON olarak gönderilir.
• Geri bildirim yoksa AI-School yalnızca iş akışının başlatıldığını doğrular ve geri kalan süreç n8n’de devam eder. Pencere bir spinner göstermez ve doğrudan kapatılabilir.
• Kayıt sırasında bu ayar açıldıysa, iş akışı ara adımları veya bitişi AI-School’a geri gönderebilir.
• Kayıt sırasında onay etkinleştirildiyse, kullanıcı seçimi doğrudan AI-School içinde yapabilir. n8n daha sonra bekleyen adımdan devam eder.

AI-School’da n8n iş akışı oluşturma

Bir yönetici iş akışını şu şekilde kaydeder:

1. Asistanlar bölümüne gidin.
2. İş akışı asistanları sekmesini açın.
3. Üstteki kartta Yeni iş akışına tıklayın ve n8n workflow seçin.
4. İş akışının adını ve n8n üretim URL’sini girin.
5. Header authentication ayarını bir header name ve gizli header value ile yapılandırın.
6. n8n’den geri bildirimler altında yalnızca bu n8n workflow’da gerçekten oluşturulmuş bölümleri işaretleyin: ilerleme, onay ve/veya iş akışının sonu.
7. Gerekirse POST request ile gönderilecek alanları ekleyin.
8. İş akışını kaydedin.

Üç geri bildirim seçeneğinin tümü varsayılan olarak kapalıdır. Daha sonra n8n’de callback veya bir onay adımı eklerseniz, AI-School’daki kaydı da güncelleyin. Böylece iletişim kutusu yalnızca bir başlangıç onayı mı göstermesi gerektiğini yoksa daha fazla sinyal beklemesi mi gerektiğini bilir.

Alanlar

• Alanlar isteğe bağlıdır.
• Her alanın bir alan adı ve bir türü vardır.
• Desteklenen alan türleri kısa metin, uzun metin, sayı, evet/hayır, tarih, tek seçim ve çoklu seçimdir.
• Tek seçim ve Çoklu seçim için kullanılabilir seçenekleri eklersiniz. Tek seçim kompakt bir açılır liste olarak gösterilir; Çoklu seçim onay kutuları gösterir. Seçilen değer veya değerler JSON body içinde gönderilir.
• Zorunlu alanlar, iş akışı başlatılmadan önce doldurulmuş olmalıdır.
• Alan adı, n8n’e gönderilen JSON body içindeki key olur.

n8n’de uyumlu bir iş akışı oluşturma

1. n8n’de yeni bir iş akışı oluşturun.
2. İlk node olarak bir Webhook ekleyin.
3. Bu node’u tam olarak Start workflow olarak adlandırın. Aşağıdaki örnekler bu adı kullanır.
4. HTTP Method ayarını POST yapın.
5. Authentication altında Header Auth seçin ve bir Header Auth credential belirleyin.
6. O credential’a, AI-School’daki iş akışı ile aynı header adı ve gizli değeri girin.
7. Respond veya Response Mode ayarını Immediately yapın. Böylece uygulama, n8n çalışmaya devam ederken doğrudan başarılı bir başlangıç onayı alır.
8. Webhook node’unun Production URL’sini AI-School’daki n8n productie-url alanına kopyalayın. /webhook-test/ içeren test URL’sini kullanmayın.
9. İş akışını n8n’de etkinleştirin.

AI-School’dan gelen veriler n8n’de body altında bulunur. Entegrasyon verileri bu nedenle body.integration altında yer alır. Bu verileri bir Edit Fields-, Set- veya Code-node içinde silmeyin. Aşağıdaki örnekler bunları her zaman doğrudan Start workflow node’undan okur.

JSON body örneği

Eğer prompt, klantnaam, doelgroepen ve datum adlarıyla alanlar tanımlarsanız, n8n örneğin şu JSON body’yi alır. AI-School integration nesnesini otomatik olarak ekler.

{
  "prompt": "Aanvraagın kısa bir özetini oluştur.",
  "klantnaam": "Örnek kuruluş",
  "doelgroepen": ["çalışanlar", "ebeveynler"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "bu-çalıştırma-için-geçici-token"
  }
}

Callback token tek bir çalıştırmaya aittir. Bunu loglarda, sabit yapılandırmada veya başka sistemlerde saklamayın.

İsteğe bağlı: ilerleme ve tamamlanmayı geri göndermek

AI-School yalnızca n8n’in geri bildirdiğini gösterebilir. Bu callback’leri yalnızca kayıt sırasında Ara ilerlemeyi bildir ve/veya İş akışının sonunu bildir seçeneklerini açtıysanız kullanın.

HTTP Request node’unu ayarlama

1. Bir HTTP Request node’u ekleyin ve buna örneğin İlerlemeyi bildir adını verin.

2. Method ayarını POST yapın.

3. URL yanında Expression seçin.

4. Tam olarak şu ifadeyi yapıştırın:

   {{ $('Start workflow').first().json.body.integration.callbackUrl }}

5. Authentication altında None seçin. Geçici token bir sonraki adımda header olarak eklenir.

6. Send Headers seçeneğini açın ve şu iki header’ı ekleyin:

   Name	Value
   Authorization	Bearer {{ $('Start workflow').first().json.body.integration.callbackToken }}
   Content-Type	application/json

7. Send Body seçeneğini açın.

8. Body Content Type: JSON ve Specify Body: Using JSON seçin.

9. Aşağıdaki JSON’u JSON alanına yapıştırın:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "document-maken-gestart",
  "type": "progress",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "document_maken",
    "label": "Belge oluşturma"
  },
  "message": "Belge oluşturuluyor."
}

10. Uygulama üzerinden iş akışını test ederken Execute step seçin. Node’un 200 durum kodu döndürmesi gerekir.

Her durum bildirimi için bu HTTP Request node’unu kopyalayın. Her kopyada en az eventId, step.id, step.label ve message değerlerini değiştirin.

Son callback’i ayarlama

İş akışının sonunu bildir etkinse, olası her yolun sonunda bir son callback bulunmalıdır. Başarı için type: "completed", sizin ele aldığınız bir hata için type: "failed" ve kullanıcı iş akışını reddettiğinde type: "rejected" kullanın.

Başarılı bir çalışma için body şu şekilde olabilir:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "workflow-afgerond",
  "type": "completed",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "afronding",
    "label": "İş akışı tamamlandı"
  },
  "message": "İş akışı tamamlandı.",
  "output": {
    "resultaat": "Kısa açıklama veya sonuca bağlantı"
  }
}

Tek bir çalışma içinde her callback için farklı bir eventId kullanın. Her zaman açık ve anlaşılır bir step.label kullanın: kullanıcı bu metni yürütme penceresinde görür.

İsteğe bağlı: uygulamada onay isteme

Wait node’unu ayarlama

1. Onayın gerektiği yere bir Wait node’u ekleyin.
2. Resume altında On Webhook Call seçin.
3. HTTP Method ayarını POST yapın.
4. Authentication altında Header Auth seçin.
5. Start workflow node’u ile aynı Header Auth credential’ını seçin.
6. Wait node’undan önce daha önce ayarlanmış HTTP Request node’unun bir kopyasını yerleştirin ve adını Onay iste yapın.
7. Bu node’da aynı dinamik URL’yi ve header’ları kullanın. Yalnızca JSON body’yi şu şekilde değiştirin:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "controle-document",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "Belgeyi kontrol et"
  },
  "approval": {
    "question": "İş akışı devam edebilir mi?",
    "context": "Önce oluşturulan belgeyi kontrol edin.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Onayla" },
      { "value": "reject", "label": "Reddet" }
    ]
  }
}

Onay iste node’unu Wait node’una bağlayın. Kullanıcı daha sonra AI-School’da düğmeleri görür. Gizli resume-url tarayıcıya verilmez; sunucu seçimi güvenli bir şekilde Wait node’una gönderir.

Wait node’undan sonraki seçimi işleme

1. Wait node’undan sonra bir Switch node’u ekleyin.

2. Kontrol edilecek değer olarak şunu kullanın:

   {{ $json.body.decision }}

3. Örneğin approve için bir yol ve reject için bir yol oluşturun.

4. Her yolu uygun bir completed, rejected veya failed callback ile bitirin.

Bir seçim değeri yalnızca harf, sayı, _ ve - içerebilir. Etiket ise normal okunabilir metin içerebilir.

Üretim callback-url’sini ayarlama

AI-School için üretim callback-url’si şudur:

https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback

Bu URL’yi her callback node’una sabit metin olarak yapıştırmayın. HTTP Request node’unun URL alanında Expression seçin ve şunu kullanın:

{{ $('Start workflow').first().json.body.integration.callbackUrl }}

Böylece AI-School her başlangıçta otomatik olarak doğru üretim URL’sini sağlar. Yukarıdaki sabit URL’yi yalnızca test sırasında ifadenin AI-School’a işaret edip etmediğini kontrol etmek için kullanın.

triggerCustomN8nWorkflow, triggerN8nWorkflow ve resumeN8nWorkflow çağrıları uygulamanın kendisi tarafından yapılır. Bu URL’leri n8n içinde ayarlamanız gerekmez.

Beklenmeyen hataları geri göndermek

Normal bir failed callback yalnızca iş akışı ilgili HTTP Request node’una ulaştığında çalışır. Beklenmeyen node hataları için ayrıca merkezi bir n8n Error Workflow kullanın.

Merkezi Error Workflow oluşturma

1. n8n’de AI-School - fouten terugsturen adında ayrı bir iş akışı oluşturun.

2. Bir Error Trigger node’u ekleyin.

3. Ardından bir HTTP Request node’u ekleyin.

4. Method ayarını POST yapın.

5. URL alanına şu sabit üretim URL’sini girin:

   https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowExecutionFailed

6. Authentication: None seçin.

7. Send Headers seçeneğini açın ve şunu ekleyin:

   Name	Value
   n8n-handihow-name	platform yöneticisinden aldığınız gizli standart değer
   Content-Type	application/json

8. Send Body seçeneğini açın, JSON seçin ve şu body’yi yapıştırın:

{
  "executionId": "{{ $json.execution.id }}",
  "workflowId": "{{ $json.workflow.id }}",
  "workflowName": "{{ $json.workflow.name }}",
  "lastNode": "{{ $json.execution.lastNodeExecuted }}",
  "message": "{{ $json.execution.error.message }}"
}

9. Error Workflow’u etkinleştirin.
10. Normal iş akışının ayarlarını açın ve Error Workflow altında bu yeni Error Workflow’u seçin.

Start workflow sonrasında her zaman en az bir ilerleme callback’i executionId: "{{ $execution.id }}" ile gönderin. Böylece uygulama, beklenmeyen bir n8n hatasının hangi çalıştırmaya ait olduğunu bilir.

Önemli kısıtlamalar

• Yalnızca webhook trigger’ları desteklenir.
• Yalnızca üretim webhook URL’leri desteklenir.
• /webhook-test/ içeren test webhook URL’leri reddedilir.
• Yalnızca POST desteklenir.
• Yalnızca genel header authentication desteklenir.
• Header değeri uygulamada gizli olarak ele alınır.
• Callback token’ları ve resume URL’leri yalnızca sunucu tarafında işlenir ve kullanıcılara doğrudan sunulmaz.
• Tenant, tarayıcının gönderdiği bir değerden değil, giriş yapmış kullanıcıdan sunucu tarafında belirlenir.

Sorun giderme

• 404 veya webhook kayıtlı değil: iş akışını n8n’de etkinleştirin ve üretim URL’sini kullanın.
• Kimlik doğrulama hatası: header name ve value’nun her iki sistemde de tam olarak aynı olduğunu kontrol edin.
• Eksik veri: uygulamadaki alan adlarının n8n’nin beklediği key’lerle eşleştiğini kontrol edin.
• n8n’de istek yok: iş akışının bir webhook trigger ile başladığını ve POST kullandığını kontrol edin.
• Yürütme penceresi dönmeye devam ediyor: İş akışının sonunu bildir seçeneğini açtıysanız, n8n’nin son bir completed, failed veya rejected callback gönderdiğini kontrol edin. Hiç geri bildirim beklemiyorsanız, kayıt sırasında üç seçeneğin de işaretini kaldırın.
• İlerleme görünmüyor: kayıt sırasında Ara ilerlemeyi bildir seçeneğinin açık olduğunu, integration nesnesinin korunduğunu ve her callback’in benzersiz bir eventId taşıdığını kontrol edin.
• Onay düğmeleri çalışmıyor: Wait node’unu, resumeUrl’yi, header authentication’ı ve choices[].value içindeki izin verilen karakterleri kontrol edin.