n8n iş akışları

AI-School, üretim webhook üzerinden n8n iş akışlarını başlatabilir. Bu, AI-School dışında otomatik bir süreci başlatmak istediğinizde faydalıdır; örneğin bir görevin oluşturulması, bir CRM kaydının güncellenmesi, bir raporlama akışının başlatılması veya form verilerinin başka bir sisteme iletilmesi gibi.

Örnek: okulun web sitesindeki haber makalesi

Diyelim ki okul, okulun WordPress sitesinde bir haber makalesini yayımlayan bir n8n iş akışına sahip. AI-School içinde yalnızca kısa bir metin yazarsınız; örneğin bir proje haftası, spor günü veya açık günle ilgili birkaç cümle. Bu metinle n8n'deki iş akışını başlatırsınız.

n8n iş akışı ardından şöyle gerçekleştirebilir:

1. Kısa metinden LLM düğümü ile okula uygun bir tonla bir taslak metin oluşturulur.
2. Okula uygun renklerde ve tanınabilir bir illustratif tarzda bir illüstrasyon için ikinci bir LLM düğümü ile görsel oluşturulur.
3. Metin ve görsel bir blog gönderisi olarak hazırlanır veya WordPress sitesinde yayımlanır.

Gibi çalışır: 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 makalesi düzgün bir şekilde web sitesine ulaşır.

Bu entegrasyon ne yapar?

İş akışını iş akışı özetinden başlatırsınız. Sadece üretim webhook, POST ve Header Auth zorunludur. n8n'den gelen alanlar ve geri bildirimler isteğe bağlıdır ve 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 başlat düğmesiyle iş akışını başlatır.
• Doldurulan değerler JSON olarak POST isteğiyle n8n webhook’una gönderilir.
• Geri bildirim olmadan AI-School yalnızca iş akışının başlatıldığını ve n8n içinde ilerlediğini teyit eder. Pencere spinner göstermez ve hemen kapatılabilir.
• Bu kayıt için etkinleştirilmişse, iş akışı ara adımları veya sonunu AI-School’a geri gönderebilir.
• Kayıtta onaylama etkinse, kullanıcı AI-School’da doğrudan bir seçim yapabilir. Ardından n8n bekleyen adımdan devam eder.

AI-School içinde n8n iş akışı oluşturma

Bir yöneticinin iş akışını şu şekilde kaydetmesi:

1. Asistanlar bölümüne gidin.
2. İş Akışlarını açın.
3. Yeni n8n iş akışını seçin.
4. İş akışının adını ve n8n üretim URL’sini girin.
5. Header kimlik doğrulama öğesini bir başlık adı ve gizli başlık değeriyle yapılandırın.
6. n8n'den geri bildirimler altında gerçekten bu n8n iş akışında oluşturulan bölümleri seçin: ilerleme, onay ve/veya iş akışının sonu.
7. POST isteğinde iletilmesi gereken alanları ekleyin.
8. İş akışını kaydedin.

Tüm üç geri bildirim seçeneği varsayılan olarak kapalıdır. Daha sonra n8n’de çağrılar veya bir onay adımı eklediğinizde, AI-School kaydını da güncelleyin. Diyalog böylece başlatma teyidi göstermesi gerektiğini ya da daha ileri sinyaller beklemesi gerektiğini bilir.

Alanlar

• Alanlar isteğe bağlıdır.
• Her alanın yalnızca bir alan adı ve bir tipi vardır.
• Desteklenen alan türleri: kısa metin, uzun metin, sayı, evet/hayır, tarih, tek seçim ve çoklu seçim.
• Tek seçim ve Çoklu seçim için mevcut seçenekler eklenir. Tek seçim kompakt bir seçim listesi olarak gösterilir; Çoklu seçim onay kutuları gösterir. Seçilen değerler JSON gövdesine iletilir.
• Zorunlu alanlar iş akışı başlatılmadan önce doldurulmalıdır.
• Alan adı JSON gövdesinde n8n’e gönderilecek anahtardır.

n8n'de Uyumlu İş Akışı Oluşturma

1. n8n'de yeni bir iş akışı oluşturun.
2. İlk düğüm olarak bir Webhook ekleyin.
3. Bu düğüme tam olarak Start workflow adını verin. Aşağıdaki örnekler bu adı kullanır.
4. HTTP Method'u POST olarak ayarlayın.
5. Authentication tarafında Header Auth seçin ve bir Header Auth kimlik bilgisi seçin.
6. AI-School'daki iş akışında aynı başlık adı ve gizli değeriyle kimlik bilgisini doldurun.
7. Respond veya Response Mode değerini Immediately olarak ayarlayın. Böylece uygulama hemen başarılı bir başlatma teyidi alır ve n8n devam eder.
8. Webhook düğümünün Üretim URL’sini kopyalayın ve AI-School’deki n8n üretim-url alanına yapıştırın. /webhook-test/ olan test URL’sini kullanmayın.
9. İş akışını n8n’de etkinleştirin.

AI-School’den gelen veriler n8n’de body altında bulunur. Entegrasyon verileri bu yüzden body.integration altında bulunur. Bu verileri Edit Fields, Set veya Code düğümü içinde değiştirmeyin. Aşağıdaki örnekler bu değeri düğünden doğrudan okur durumda gösterir.

JSON body örneği

Alanları prompt, klantnaam, doelgroepen ve datum adlarıyla tanımlarsanız, n8n şu JSON gövdesini alır. AI-School otomatik olarak integration nesnesini ekler.

{
  "prompt": "Maak een korte samenvatting van de aanvraag.",
  "klantnaam": "Voorbeeldorganisatie",
  "doelgroepen": ["medewerkers", "ouders"],
  "datum": "2026-09-22",
  "integration": {
    "runId": "chat-document-id",
    "tenant": "default",
    "callbackUrl": "https://europe-west1-ai-school-pro.cloudfunctions.net/n8nWorkflowCallback",
    "callbackToken": "tijdelijk-token-voor-deze-uitvoering"
  }
}

Çağrı geri bildirimi için tek bir çalışma için olan callbackToken kaydının bir parçasıdır. Loglarda, sabit konfigürasyonda veya diğer sistemlerde saklamayın.

İsteğe Bağlı: ilerleme ve tamamlanma geri bildirimleri

AI-School yalnızca n8n’nin geri bildirimlerini gösterebilir. Bu geri bildirimleri yalnızca kayıt sırasında Ara ilerleme bildirin ve/veya İş akışının sonunda bildirin seçeneklerini etkinleştirdiyseniz kullanın.

HTTP Request düğümü ayarlama

1. Bir HTTP Request düğümü ekleyin ve buna örneğin İlerlemeyi Bildir adını verin.

2. Methodu POST olarak ayarlayın.

3. URL üzerinde Expression seçeneğini tıklayın.

4. Aşağıdaki ifadeyi tam olarak yapıştırın:

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

5. Authentication için None seçin. Geçici token bir sonraki adımda başlık olarak eklenir.

6. Send Headers açık olsun ve şu iki başlığı ekleyin:

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

7. Send Body açık olsun.

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

9. Aşağıdaki JSONu 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": "Document maken"
  },
  "message": "Het document wordt gemaakt."
}

10. Düğümün durumunu test ederken adımı çalıştırın. Düğümün durumunun 200 dönüşü alması gerekir.

Bu HTTP Request düğümünü her durum bildirimi için kopyalayın. Kopya başına en az eventId, step.id, step.label ve message değerlerini değiştirin.

Son çağrıyı ayarlama

İş akışının sonunda bildirin etkinleştirilmişse, her olası rota sonunda bir son geri bildirimi bulunmalıdır. Başarılı için type: "completed", bir hata için kendi işlediğiniz hatayı belirten type: "failed" ve kullanıcı iş akışını reddederse type: "rejected" kullanın.

Başarılı bir yürütme için gövde ş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": "Workflow afgerond"
  },
  "message": "İş akışı tamamlandı.",
  "output": {
    "sonuç": "Kısa bir açıklama veya sonuca bağlantı"
  }
}

Her bir geri bildirim için tek bir yürütme içinde farklı bir eventId kullanın. Ayrıca kullanıcıya bu yürütmede görünen metin olan step.label için her zaman net bir ifade kullanın.

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

Wait düğümü ayarlama

1. Onay gerektiği yerde bir Wait düğümü ekleyin.
2. Resume için On Webhook Call seçin.
3. HTTP Methodu POST olarak ayarlayın.
4. Authentication için Header Auth seçin.
5. Start workflow düğümündeki aynı Header Auth kimlik bilgisini seçin.
6. Wait düğümünden önce daha önce ayarlanmış HTTP Request düğümünün bir kopyasını ekleyin ve buna Vraag goedkeuring adını verin.
7. Bu düğümde aynı dinamik URL ve başlıkları kullanın. Sadece JSON gövdesini ş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": "Document controleren"
  },
  "approval": {
    "question": "Mag de workflow doorgaan?",
    "context": "Controleer eerst het gegenereerde document.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Goedkeuren" },
      { "value": "reject", "label": "Afwijzen" }
    ]
  }
}

İsteğe bağlı: Onay isteme düğümünü Wait düğümüne bağlayın. Kullanıcı ardından AI-School’da butonları görür. Gizli resume-url tarayıcıya gösterilmez; sunucu onayı güvenli bir şekilde Wait düğümüne iletir.

Wait düğümünden sonraki seçimi işleme

1. Wait düğümünden sonra bir Switch düğümü ekleyin.

2. Kontrol edilecek değeri şu şekilde kullanın:

   {{ $json.body.decision }}

3. Örneğin approve ve reject için birer rota oluşturun.

4. Her rotayı uygun bir completed, rejected veya failed geri bildirimi ile sonlandırın.

Bir seçim değeri yalnızca harfler, rakamlar, _ ve - içerebilir. Etiket kullanıcı için okunabilir metin içermelidir.

Üretim callback-url ayarlama

AI-School için üretim callback-url şu şekildedir:

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

Bu URL’yi her geri bildirim düğümünde sabit metin olarak yapıştırmayın. HTTP Request düğümünün URL alanında Expression seçeneğini kullanın ve şu ifadeyi kullanın:

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

AI-School bu şekilde her başlatmada doğru üretim URL’sini otomatik olarak verir. Yukarıdaki sabit URL yalnızca test sırasında ifadeyi AI-School’a yönlendirdiğini kontrol etmek için kullanılır.

triggerCustomN8nWorkflow, triggerN8nWorkflow ve resumeN8nWorkflow çağrıları uygulama tarafından kendiliğinden yapılır. Bu URL’leri n8n içinde ayarlamanıza gerek yoktur.

Beklenmeyen hataları geri göndermek

Normal bir failed geri bildirimi yalnızca iş akışı ilgili HTTP Request düğümüne ulaştığında çalışır. Beklenmeyen düğüm hataları için merkezi bir n8n Hata İş Akışı kullanın.

Merkezi Hata İş Akışı oluşturma

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

2. Bir Error Trigger düğümü ekleyin.

3. Ardından bir HTTP Request düğümü ekleyin.

4. Method olarak POST seçin.

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

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

6. Authentication: None seçin.

7. Send Headers açık olsun ve şu başlıkları ekleyin:

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

8. Send Body açık olsun, JSON seçin ve şu gövdeyi 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. Hata İş Akışını etkinleştirin.
10. Normal iş akışının ayarlarına gidin ve Error Workflow olarak bu yeni Hata İş Akışını seçin.

Başlatma işleminden sonra en az bir ilerleme geri bildirimi gönderin: executionId: "{{ $execution.id }}". Böylece uygulama hangi çalışmanın beklenmeyen bir n8n hatasına uğradığını bilir.

Önemli sınırlamalar

• Yalnızca webhook tetikleyicileri desteklenir.
• Yalnızca üretim webhook URL’leri desteklenir.
• /webhook-test/ ile test webhook URL’leri reddedilir.
• Yalnızca POST desteklenir.
• Yalnızca genel başlık kimlik doğrulama desteklenir.
• Başlık değeri uygulamada sır olarak ele alınır.
• Geri bildirim tokenleri ve resume-url’ler yalnızca sunucu tarafında işlenir ve kullanıcılar için doğrudan erişilebilir değildir.
• Tenant, giriş yapan kullanıcıdan sunucu tarafında belirlenir; tarayıcı tarafından gönderilen bir değere bağlı değildir.

Problemler çözme

• 404 veya webhook kaydı yok: n8n’de iş akışını etkinleştirin ve üretim URL’sini kullanın.
• Kimlik doğrulama hatası: başlık adı ve değerin iki sistemde de tam olarak aynı olduğundan emin olun.
• Eksik veri: uygulamadaki alan adlarının, n8n’in beklediği anahtar adlarıyla eşleştiğini kontrol edin.
• n8n’de istek yok: iş akışının bir webhook tetikleyicisiyle başlamasından ve POST kullanmasından emin olun.
• Yürütme penceresi dönmeyi durdurmuyorsa: İş akışının sonunda bildirin özelliğinin açık olduğundan emin olun; yoksa tüm geri bildirim seçeneklerini devre dışı bırakın.
• İlerleme görünmüyor: kayıt sırasında Ara ilerleme bildirin açık mı, integration nesnesi korunuyor mu ve her geri bildirimin benzersiz bir eventId içerdiğini kontrol edin.
• Onay düğmeleri çalışmıyor: Wait düğümünü, resumeUrl'ı, başlık kimlik doğrulamayı ve choices[].value içindeki izin verilen karakterleri kontrol edin.