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
- Lege im empfangenden System einen Webhook an und kopiere dessen Adresse. Sie muss mit
https://beginnen und öffentlich erreichbar sein (interne Adressen siehe unten). - Öffne Einstellungen → Integrationen → Kanal hinzufügen → Webhook (JSON), gib Name und Webhook-Adresse ein, wähle Ereignisse, Sprache und Zeitzone und klicke Speichern.
- 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. - 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.
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-apikeymit dem API-Schlüssel des Make-Webhooks,AuthorizationmitBearer <Token>für ein eigenes System.
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,dataundfields[].key– sie ändern sich nicht mit der Sprache.title,textundlabelsind für Menschen gedacht. - Beträge stehen in
dataals ganze Zahl in Cent (amountCents) mitcurrency(ISO 4217, z. B.EUR). Zeitpunkte indatasind ISO 8601 in UTC. - Bei Ohne Namen fehlen alle Personennamen in
textundfieldssowiedata.userIdunddata.ownerUserId. - Das Schema wächst nur additiv: Neue Felder, Ereignisse und
data-Schlüssel können hinzukommen – ignoriere Unbekanntes. Eine inkompatible Änderung käme alsquicktribe.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:
- Header lesen und in
tundv1zerlegen. - Prüfen, dass
thöchstens 300 Sekunden von der aktuellen Zeit abweicht (Schutz vor wiederverwendeten Nachrichten). - Den HMAC über
t + "." + bodymit deinem Schlüssel berechnen und in konstanter Zeit mitv1vergleichen. - 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 demselbenX-QuickTribe-Delivery), aber einem neuen Zeitstempeltund 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 mit2xx 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 undhttps:// 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.