n8n przepływy pracy

AI-School może uruchamiać przepływy pracy w n8n za pomocą produkcyjnego webhooka. To przydatne, gdy poza AI-School chcesz uruchomić zautomatyzowany proces, na przykład stworzenie zadania, aktualizację rekordu CRM, uruchomienie przepływu raportowania lub przekazanie danych z formularza do innego systemu.

Przykład: artykuł informacyjny na stronie szkoły

Załóżmy, że szkoła stworzyła przepływ pracy w n8n, który publikuje artykuł informacyjny na stronie WordPress szkoły. W AI-School wpisujesz wtedy jedynie krótki tekst, na przykład kilka zdań o tygodniu projektowym, dniu sportu lub dniu otwartym. Taki tekst uruchamia przepływ pracy w n8n.

Przepływ pracy w n8n może następnie na przykład:

1. Z krótkiego tekstu stworzyć schludny tekst roboczy za pomocą węzła LLM i prompta dopasowanego do tonu szkoły.
2. Wykonać odpowiednią ilustrację za pomocą drugiego węzła LLM, na przykład w kolorach szkoły i w rozpoznawalnym stylu ilustracyjnym.
3. Przygotować lub opublikować tekst i grafikę jako wpis na blogu na stronie WordPress.

Tak AI-School i n8n współpracują: w AI-School użytkownik wybiera przepływ pracy i wprowadza potrzebne informacje. Następnie n8n wykonuje zautomatyzowane kroki i zapewnia, że artykuł informacyjny trafi na stronę w odpowiedni sposób.

Co robi ta integracja?

Uruchamiasz przepływ pracy w n8n z widoku przepływów. Obowiązkowy jest jedynie webhook produkcyjny, POST i uwierzytelnianie nagłówkami (Header Auth). Pola i potwierdzenia zwrotne z n8n są opcjonalne i mogą być ustawione niezależnie od siebie.

• Jeśli przepływ pracy nie ma pól, webhook zostaje wywołany od razu.
• Jeśli przepływ ma pola, najpierw otwiera się formularz. Użytkownik wprowadza pola i uruchamia przepływ za pomocą przycisku.
• Wartości wypełnione są wysyłane jako JSON w żądaniu POST do webhooka n8n.
• Bez potwierdzeń zwrotnych AI-School potwierdza jedynie, że przepływ pracy został uruchomiony i kontynuuje w n8n. Okno nie wyświetla spinnera i można je od razu zamknąć.
• Jeśli to włączono przy rejestracji, przepływ może wysyłać w trakcie wykonywania pośrednie kroki lub koniec z powrotem do AI-School.
• Jeśli zatwierdzenie przy rejestracji jest włączone, użytkownik może dokonać wyboru bezpośrednio w AI-School. Następnie n8n kontynuje od kroków oczekujących.

Tworzenie przepływu n8n w AI-School

Administrator rejestruje przepływ pracy w następujący sposób:

1. Przejdź do Asystenci.
2. Otwórz Przepływy.
3. Wybierz Nowy przepływ n8n.
4. Wpisz nazwę przepływu i adres produkcyjny n8n.
5. Skonfiguruj Header authentication z nazwą nagłówka i tajną wartością nagłówka.
6. W sekcji Terugmeldingen uit n8n zaznacz tylko te elementy, które faktycznie zostały zbudowane w tym przepływie n8n: postęp, zatwierdzenie i/lub koniec przepływu.
7. Opcjonalnie dodaj pola, które mają być wysyłane w żądaniu POST.
8. Zapisz przepływ.

Wszystkie trzy opcje powiadomień domyślnie są wyłączone. Jeśli później dodasz callbacki lub krok zatwierdzający w n8n, zaktualizuj także rejestrację w AI-School. Dialog będzie wtedy wiedział, czy ma pokazać tylko potwierdzenie uruchomienia, czy czekać na dalsze sygnały.

Pola

• Pola są opcjonalne.
• Każde pole ma jedną nazwę pola i typ.
• Obsługiwane typy pól to krótki tekst, długi tekst, liczba, tak/nie, data, jeden wybór i wiele wyborów.
• Dla Jednego wyboru i Wielu wyborów dodaj dostępne opcje. Jedno wybranie wyświetla się jako kompaktowa lista rozwijana; Wiele wyborów wyświetla pola wyboru. Wybrana wartość lub wartości są wysyłane w ciele JSON.
• Pola obowiązkowe muszą być wypełnione przed uruchomieniem przepływu.
• Nazwa pola staje się kluczem w ciele JSON wysyłanym do n8n.

Tworzenie zgodnego przepływu pracy w n8n

1. Utwórz w n8n nowy przepływ pracy.
2. Dodaj jako pierwszą node Webhook.
3. Nadaj tej node dokładnie nazwę Start workflow. Przykłady dalej używają tej nazwy.
4. Ustaw HTTP Method na POST.
5. Wybierz Authentication na Header Auth i wybierz poświadczenie Header Auth.
6. W tym poświadczeniu wpisz tę samą nazwę nagłówka i tajną wartość, co w przepływie w AI-School.
7. Ustaw Respond lub Response Mode na Immediately. Aplikacja otrzyma wtedy natychmiast potwierdzenie rozpoczęcia, podczas gdy n8n będzie kontynuować.
8. Skopiuj Production URL węzła Webhook do pola n8n produkcy URL w AI-School. Nie używaj testowego URL-a z /webhook-test/.
9. Aktywuj przepływ w n8n.

Dane z AI-School znajdują się w n8n pod body. Dane integracyjne znajdują się pod body.integration. Nie usuwaj tych danych w Edycie pól, Ustaw lub Node Kodu. Poniższe przykłady zawsze odczytują je bezpośrednio z węzła Start workflow.

Przykład ciała JSON

Jeśli zdefiniujesz pola o nazwach prompt, klantnaam, doelgroepen i datum, n8n otrzyma na przykład takie ciało JSON. AI-School automatycznie dodaje obiekt integration.

{
  "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"
  }
}

Token zwrotny wywołania należy do jednego uruchomienia. Nie zapisuj go w logach, stałej konfiguracji ani w innych systemach.

Opcjonalnie: zwroty postępów i zakończenia

AI-School może wyświetlać tylko to, co zwróci n8n. Używaj tych powiadomień zwrotnych tylko wtedy, gdy w rejestracji włączysz Powiadamiaj o postępach w czasie i/lub Powiadamiaj o zakończeniu przepływu.

Konfiguracja węzła HTTP Request

1. Dodaj węzeł HTTP Request i nazwij go na przykład Powiadom o postępie.

2. Ustaw Method na POST.

3. Kliknij przy URL na Expression.

4. Wklej dokładnie tę wyrażenie:

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

5. Wybierz Authentication na None. Tymczasowy token zostanie dodany w nagłówkach na kolejnym kroku.

6. Włącz Send Headers i dodaj te dwa nagłówki:

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

7. Włącz Send Body.

8. Wybierz Body Content Type: JSON i Specify Body: Using JSON.

9. Wklej poniższe JSON w polu JSON:

{
  "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": "Dokument tworzenie"
  },
  "message": "Dokument jest tworzony."
}

10. Wybierz Execute step podczas testowania przepływu w aplikacji. Node powinien zwrócić status 200.

Skopiuj ten węzeł HTTP Request dla każdego statusu. Dla każdej kopii zmień przynajmniej eventId, step.id, step.label i message.

Ustawienie ostatniego callbacku

Jeśli włączono Powiadomienie o zakończeniu przepływu, na końcu każdej możliwej ścieżki musi być ostatni callback. Używaj type: "completed" przy pomyślnym zakończeniu, type: "failed" przy błędzie, który sam obsługujesz, i type: "rejected" gdy użytkownik odrzuci przepływ.

Dla prawidłowego wykonania ciało może wyglądać tak:

{
  "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 zakończony"
  },
  "message": "Przepływ został zakończony.",
  "output": {
    "resultaat": "Krótki opis lub link do wyniku"
  }
}

W jednej realizacji użyj dla każdego callback innego eventId. Zawsze używaj jasnego step.label: ten tekst widzi użytkownik w oknie wykonania.

Opcjonalnie: zapytanie o zatwierdzenie w aplikacji

Ustawienie węzła Wait

1. Dodaj węzeł Wait w miejscu, gdzie potrzebne jest zatwierdzenie.
2. Wybierz Resume na On Webhook Call.
3. Ustaw HTTP Method na POST.
4. Wybierz Authentication na Header Auth.
5. Wybierz te same poświadczenia Header Auth co w węźle Start workflow.
6. Przed węzłem Wait umieść kopię wcześniej skonfigurowanego węzła HTTP Request i nazwij ją Zapytaj o zatwierdzenie.
7. Użyj w tym węźle tej samej dynamicznej URL i nagłówków. Zastąp tylko ciało JSON następującym:

{
  "tenant": "{{ $('Start workflow').first().json.body.integration.tenant }}",
  "runId": "{{ $('Start workflow').first().json.body.integration.runId }}",
  "eventId": "kontrola-dokumentu",
  "type": "approval_required",
  "executionId": "{{ $execution.id }}",
  "step": {
    "id": "controle_document",
    "label": "Dokument kontrolować"
  },
  "approval": {
    "question": "Czy przepływ może kontynuować?",
    "context": "Najpierw sprawdź wygenerowany dokument.",
    "resumeUrl": "{{ $execution.resumeUrl }}",
    "choices": [
      { "value": "approve", "label": "Zatwierdzić" },
      { "value": "reject", "label": "Odrzucić" }
    ]
  }
}

Połącz Zapytaj o zatwierdzenie z węzłem Wait. Użytkownik zobaczy wtedy przyciski w AI-School. Tajny URL wznowienia nie jest podany w przeglądarce; serwer bezpiecznie przekazuje wybór do węzła Wait.

Przetwarzanie wyboru po Wait

1. Dodaj po węźle Wait węzeł Switch.

2. Użyj jako wartości do sprawdzenia:

   {{ $json.body.decision }}

3. Utwórz na przykład ścieżkę dla approve i ścieżkę dla reject.

4. Zakończ każdą ścieżkę odpowiednim callbackiem: completed, rejected lub failed.

Wartość wyboru może zawierać tylko litery, cyfry, _ i -. Etykieta może zawierać czytelny tekst.

Ustawienie produkcyjnego URL callback

Produkcja callback-url dla AI-School to:

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

Nie wkładaj tego URL-a jako stały tekst w każdą węzeł callback. W polu URL węzła HTTP Request wybierz Expression i użyj:

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

AI-School zapewni przy każdym uruchomieniu właściwy produkcyjny URL. Stały URL powyżej użyjesz tylko do testów, aby sprawdzić, czy wyrażenie odnosi się do AI-School.

Wywołania triggerCustomN8nWorkflow, triggerN8nWorkflow i resumeN8nWorkflow będą wywoływane przez samą aplikację. Nie musisz konfigurować tych URL-i w n8n.

Wysyłanie nieoczekiwanych błędów

Standardowy callback failed działa tylko wtedy, gdy odpowiedni węzeł HTTP Request osiąga status. W przypadku nieoczekiwanych błędów węzłów użyj centralnego n8n Error Workflow.

Tworzenie Centralnego Error Workflow

1. W n8n utwórz osobny przepływ o nazwie AI-School - błędy zwrotne.

2. Dodaj węzeł Error Trigger.

3. Następnie dodaj węzeł HTTP Request.

4. Ustaw Method na POST.

5. Wpisz w URL ten stały, produkcyjny URL:

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

6. Wybierz Authentication: None.

7. Włącz Send Headers i dodaj:

   Name	Value
   n8n-handihow-name	tajna wartość domyślna, którą otrzymasz od administratora platformy
   Content-Type	application/json

8. Włącz Send Body, wybierz JSON i wklej treść:

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

9. Aktywuj Error Workflow.
10. Otwórz ustawienia zwykłego przepływu i w sekcji Error Workflow wybierz tę nową Error Workflow.

Zapisuj zawsze po Start workflow co najmniej jeden callback postępu z executionId: "{{ $execution.id }}". Dzięki temu aplikacja wie, przy której wykonaniu pojawił się nieoczekiwany błąd n8n.

Ważne ograniczenia

• Obsługiwane są tylko wyzwalacze webhook.
• Obsługiwane są tylko URL-ki webhook produkcyjnych.
• Testowe webhooki z /webhook-test/ są odrzucane.
• Obsługiwane jest tylko POST.
• Obsługiwane jest tylko uwierzytelnianie nagłówkami ogólnymi (generic header authentication).
• Wartość nagłówka traktowana jest w aplikacji jako tajemnica.
• Tokeny callback i URL-e wznowienia są przetwarzane wyłącznie po stronie serwera i nie są dostępne bezpośrednio dla użytkowników.
• Tenant określany jest po stronie serwera na podstawie zalogowanego użytkownika, a nie na podstawie wartości wysyłanej przez przeglądarkę.

Rozwiązywanie problemów

• 404 lub webhook nie zarejestrowany: aktywuj przepływ w n8n i użyj produkcyjnego URL.
• Błąd uwierzytelniania: sprawdź, czy nazwa nagłówka i wartość są takie same w obu systemach.
• Brak danych: sprawdź, czy nazwy pól w aplikacji odpowiadają kluczom, których oczekuje n8n.
• Brak żądania w n8n: sprawdź, czy przepływ zaczyna się od webhook trigger i używa POST.
• Okno wykonania kręci się: jeśli włączono Powiadomienie o zakończeniu przepływu, sprawdź, czy n8n wysyła ostatnie completed, failed lub rejected callback. Jeśli nie oczekujesz żadnych powiadomień zwrotnych, wyłącz wszystkie trzy opcje w rejestracji.
• Brak widocznego postępu: sprawdź, czy w rejestracji aktywowane jest Powiadomienie o postępie lub czy obiekt integration jest zachowany i czy każdy callback ma unikalny eventId.
• Przyciski zatwierdzania nie działają: sprawdź węzeł Wait, resumeUrl, uwierzytelnianie nagłówków oraz dozwolone znaki w choices[].value.