Mit n8n verarbeitest du Nachrichten des allgemeinen Webhooks weiter – etwa um neue Mitglieder in eine Tabelle zu schreiben oder dem Team eine E-Mail zu schicken. Die Anleitung gilt für n8n 2.x (n8n Cloud und selbst gehostet); Unterschiede zu 1.x sind vermerkt.

1. Webhook-Trigger anlegen

  1. Lege einen neuen Workflow an und füge als Trigger Webhook („On webhook call“) hinzu.
  2. Stelle ein:
    • HTTP Method: POST
    • Path: z. B. quicktribe (oder die vorgeschlagene zufällige ID)
    • Authentication: None – die Echtheit prüft die Signatur (siehe unten)
    • Respond: Immediately – QuickTribe bekommt sofort eine Antwort
  3. Unter Options → Add Option wähle Raw Body und schalte es ein. Nur dann stehen die unveränderten Bytes für die Signaturprüfung zur Verfügung (als Binärdaten data, zusätzlich zu body, headers usw.).
  4. Oben im Node gibt es Test URL und Production URL. In QuickTribe gehört die Production URL (https://<dein-n8n>/webhook/<path>).

2. Kanal in QuickTribe anlegen

  1. Einstellungen → Integrationen → Kanal hinzufügen → Webhook (JSON).
  2. Trage die Production URL ein, wähle die Ereignisse und Speichern.
  3. Kopiere den angezeigten Signaturschlüssel.
Liegt n8n in eurem internen Netz, muss der Betreiber der QuickTribe-Installation den Host über APP_INTEGRATION_ALLOWED_HOSTS freigeben (siehe Konfiguration).

3. Testnachricht empfangen

Zum Entwerfen des Workflows kannst du vorübergehend die Test URL (/webhook-test/…) als Adresse in QuickTribe eintragen: Klicke in n8n auf Listen for test event und innerhalb von 120 Sekunden in QuickTribe auf Testnachricht senden. Die Daten erscheinen dann im Editor. Trage danach wieder die Production URL ein.
Die Test URL lauscht nur kurz nach „Listen for test event“. Steht sie dauerhaft in QuickTribe, antwortet n8n mit 404 – QuickTribe pausiert den Kanal dann.

4. Signatur prüfen

Variante A: Code-Node mit crypto

Füge direkt hinter dem Webhook einen Code-Node hinzu (Mode: Run Once for All Items, Language: JavaScript):
Header-Namen sind in n8n kleingeschrieben. Ist die Signatur ungültig, bricht die Ausführung ab und erscheint unter Executions als Fehler (QuickTribe hat wegen „Respond: Immediately“ trotzdem schon eine Antwort bekommen). crypto freigeben: In n8n Cloud ist crypto im Code-Node verfügbar. Selbst gehostet sind Modulimporte standardmäßig gesperrt: Im internen Runner-Modus setzt der n8n-Betreiber NODE_FUNCTION_ALLOW_BUILTIN=crypto und startet n8n neu; mit externen Task-Runnern (n8nio/runners) gehört die Freigabe laut n8n-Dokumentation in die Datei /etc/n8n-task-runners.json (env-override). Kannst du das nicht setzen, nimm Variante B.

Variante B: ohne Modulfreigabe (Code → Crypto → Code)

  1. Code-Node, bereitet die Prüfung vor:
  2. Crypto-Node: Action Hmac, Type SHA256, Value {{ $json.signedPayload }}, Property Name expected, Encoding HEX. Den Signaturschlüssel trägst du in der Credential Crypto im Feld Hmac Secret ein (in älteren n8n-Versionen steht das Feld direkt im Node).
  3. Code-Node, vergleicht ohne Zeitunterschiede:

Schlüssel ablegen

Seit n8n 2.0 ist der Zugriff auf Umgebungsvariablen im Code-Node standardmäßig gesperrt ($env funktioniert dann nicht). Steht der Schlüssel direkt im Code, sehen ihn alle, die den Workflow bearbeiten dürfen. Sicherer ist Variante B mit der Crypto-Credential.

5. Veröffentlichen

Klicke oben rechts auf Publish (n8n 1.x: Schalter Active). Erst dann ist die Production URL registriert; ohne Veröffentlichung antwortet sie mit 404 und QuickTribe pausiert den Kanal. Ausführungen über die Production URL siehst du unter Executions.

Beispiel: neue Mitglieder in eine Tabelle

  1. Hinter der Signaturprüfung ein Switch auf {{ $json.event }}, Regel is equal to member.joined.
  2. Im Zweig member.joined: Google Sheets → Append Row mit den Spalten {{ $json.occurredAt }}, {{ $json.community.name }}, {{ $json.text }} und {{ $json.data.userId }}.
  3. Andere Ereignisse, z. B. member.join_requested: Send Email mit Betreff {{ $json.title }}, Text {{ $json.text }} und Link {{ $json.link.url }}.
Speichere die deliveryId mit und prüfe vor dem Anhängen auf Dubletten – QuickTribe wiederholt eine Nachricht, wenn n8n nicht rechtzeitig antwortet.

Stolpersteine

  • Ohne Raw Body gibt es keine Originalbytes; ein JSON.stringify($json.body) weicht ab und die Signatur schlägt fehl.
  • Hinter einem Reverse Proxy muss n8n WEBHOOK_URL kennen, sonst zeigt es falsche Adressen an.