Der Kanaltyp Webhook (JSON) schickt jedes abonnierte Ereignis als HTTP-POST mit einem JSON-Dokument an eine Adresse deiner Wahl – zum Beispiel an einen Webhook-Trigger in n8n, Make, Zapier oder an ein eigenes System. Jede Nachricht ist mit einem eigenen Schlüssel signiert, damit der Empfänger prüfen kann, dass sie wirklich von deiner Community kommt.

Einrichten

  1. Lege im empfangenden System einen Webhook an und kopiere dessen Adresse. Sie muss mit https:// beginnen und öffentlich erreichbar sein (interne Adressen siehe unten).
  2. Öffne Einstellungen → Integrationen → Kanal hinzufügen → Webhook (JSON), gib Name und Webhook-Adresse ein, wähle Ereignisse, Sprache und Zeitzone und klicke Speichern.
  3. QuickTribe zeigt jetzt einmalig den Signaturschlüssel an (beginnt mit qtwhsec_). Kopiere ihn und lege ihn im empfangenden System ab. Er wird danach nie wieder angezeigt.
  4. Klicke Testnachricht senden. Der Empfänger bekommt eine vollständige Beispielnachricht mit "event": "integration.test" und "test": true – Werkzeuge wie Make und Zapier lesen daraus die Datenstruktur ab.
Schlüssel neu erzeugen ersetzt den Signaturschlüssel sofort; der alte gilt ab diesem Moment nicht mehr. Bei Owner-Kanälen (mit Zahlungs-Ereignissen) kann das nur der Owner.

Zusätzlicher Header

Manche Werkzeuge können die Signatur nicht zuverlässig prüfen, aber einen festen Geheimwert in einem Header. Dafür kannst du unter Zusätzlicher Header (optional) genau einen Header mit Header-Name und Header-Wert festlegen, zum Beispiel:
  • x-make-apikey mit dem API-Schlüssel des Make-Webhooks,
  • Authorization mit Bearer <Token> für ein eigenes System.
Der Wert wird wie die Adresse verschlüsselt gespeichert und nie wieder angezeigt (nur „gesetzt“). Lässt du das Wertfeld beim Bearbeiten leer, bleibt er unverändert; leerst du den Namen, entfällt der Header. Nicht erlaubt sind Transport-Header wie Host, Content-Type oder Content-Length und Namen, die mit X-QuickTribe- beginnen.

Request

Der Body ist höchstens 64 KB groß und kompakt als UTF-8 serialisiert.

Schema quicktribe.announcement.v1

Hinweise:
  • Für die Weiterverarbeitung nutze event, data und fields[].key – sie ändern sich nicht mit der Sprache. title, text und label sind für Menschen gedacht.
  • Beträge stehen in data als ganze Zahl in Cent (amountCents) mit currency (ISO 4217, z. B. EUR). Zeitpunkte in data sind ISO 8601 in UTC.
  • Bei Ohne Namen fehlen alle Personennamen in text und fields sowie data.userId und data.ownerUserId.
  • Das Schema wächst nur additiv: Neue Felder, Ereignisse und data-Schlüssel können hinzukommen – ignoriere Unbekanntes. Eine inkompatible Änderung käme als quicktribe.announcement.v2.

Ereignisse und data

Plattform-Admins bekommen zusätzlich die Plattform-Ereignisse im selben Schema.

Signatur prüfen

QuickTribe berechnet für jeden Zustellversuch:
t ist die Unix-Zeit des Versuchs in Sekunden, body sind die unveränderten Bytes des Request-Bodys. So prüfst du:
  1. Header lesen und in t und v1 zerlegen.
  2. Prüfen, dass t höchstens 300 Sekunden von der aktuellen Zeit abweicht (Schutz vor wiederverwendeten Nachrichten).
  3. Den HMAC über t + "." + body mit deinem Schlüssel berechnen und in konstanter Zeit mit v1 vergleichen.
  4. Erst danach das JSON auswerten.
Prüfe immer über den Rohbody. Wer das JSON erst einliest und wieder serialisiert, verändert Leerzeichen, Unicode-Zeichen oder die Reihenfolge – die Signatur passt dann nicht mehr.

Wiederholte Nachrichten erkennen

  • Replay-Schutz: Die Toleranz von 300 Sekunden verhindert, dass eine abgefangene Nachricht später erneut eingespielt wird. Achte auf eine korrekt gehende Uhr (NTP) beim Empfänger.
  • Idempotenz: Bei Wiederholungen schickt QuickTribe denselben Body mit derselben id (und demselben X-QuickTribe-Delivery), aber einem neuen Zeitstempel t und damit einer neuen Signatur. Speichere verarbeitete IDs einige Tage und überspringe Nachrichten, deren ID du schon kennst. So entsteht auch dann kein doppelter Eintrag, wenn deine Antwort unterwegs verloren ging.

Antwortcodes und Wiederholungen

Antworte schnell (QuickTribe wartet höchstens 5 Sekunden auf die Verbindung und 10 Sekunden insgesamt) – am besten sofort mit 2xx und die eigentliche Verarbeitung danach. Nach 5 endgültig gescheiterten Nachrichten in Folge pausiert der Kanal ebenfalls; Owner und Admins bekommen eine Glocke. Jede erfolgreiche Zustellung setzt den Zähler zurück. Wie du einen Kanal fortsetzt, steht in der Übersicht. Die Reihenfolge der Nachrichten ist nicht garantiert – insbesondere nach Wiederholungen. Sortiere bei Bedarf nach occurredAt.

Interne Adressen

Zieladressen müssen öffentlich erreichbar sein und https:// mit Port 443 nutzen; Adressen im internen Netz, localhost und IP-Adressen lehnt QuickTribe ab. Läuft dein Empfänger (z. B. ein selbst gehostetes n8n) im internen Netz, kann der Betreiber den Host über APP_INTEGRATION_ALLOWED_HOSTS freigeben. Freigegebene Hosts dürfen auch http:// und andere Ports nutzen.