---
title: "Allgemeiner Webhook (JSON)"
description: "Signiertes JSON für n8n, Make, Zapier und eigene Systeme: Schema quicktribe.announcement.v1 mit allen Feldern und data-Schlüsseln je Ereignis, Header, Signaturprüfung in PHP, Node.js und Python, Replay-Schutz, Idempotenz, Wiederholungen und Antwortcodes"
---

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](/handbuch/owner/integrationen/n8n), [Make](/handbuch/owner/integrationen/make), [Zapier](/handbuch/owner/integrationen/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](#interne-adressen)).
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

```http
POST /dein/webhook HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: QuickTribeIntegration/1.0 (+https://deine-plattform.example)
X-QuickTribe-Event: member.joined
X-QuickTribe-Delivery: 0192a7c4-6d1e-7c3a-9f10-2b5e8d0c4a11
X-QuickTribe-Signature: t=1760343300,v1=5f0c9a…(64 Hex-Zeichen)
```

| Header | Inhalt |
| --- | --- |
| `X-QuickTribe-Event` | Ereignis-Schlüssel, gleich dem Feld `event` |
| `X-QuickTribe-Delivery` | ID der Nachricht, gleich dem Feld `id`. Bleibt bei Wiederholungen gleich – nutze sie, um doppelte Zustellungen zu erkennen. |
| `X-QuickTribe-Signature` | `t=<Unix-Zeit in Sekunden>,v1=<Signatur>` – siehe [Signatur prüfen](#signatur-prüfen) |
| optional dein Zusatz-Header | wie unter **Zusätzlicher Header** eingestellt |

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

## Schema `quicktribe.announcement.v1`

```json
{
  "schema": "quicktribe.announcement.v1",
  "id": "0192a7c4-6d1e-7c3a-9f10-2b5e8d0c4a11",
  "event": "plan.subscribed",
  "test": false,
  "severity": "info",
  "occurredAt": "2026-10-13T08:15:00+00:00",
  "locale": "de",
  "timezone": "Europe/Berlin",
  "community": { "id": "0191f3e2-…", "slug": "lauftreff-nord", "name": "Lauftreff Nord" },
  "title": "Neuer Plan gebucht",
  "text": "Anna Beispiel hat „Premium“ gebucht.",
  "fields": [
    { "key": "member", "label": "Mitglied", "value": "Anna Beispiel" },
    { "key": "plan", "label": "Plan", "value": "Premium" },
    { "key": "price", "label": "Preis", "value": "9,90 € · monatlich" }
  ],
  "data": {
    "userId": "0191f3e2-…",
    "planId": "0191f400-…",
    "source": "purchase",
    "subscriptionId": "0192a7c4-…",
    "amountCents": 990,
    "currency": "EUR",
    "interval": "month"
  },
  "link": { "url": "https://deine-plattform.example/c/lauftreff-nord/members/0191f3e2-…", "label": "Mitglied öffnen" }
}
```

| Feld | Typ | Bedeutung |
| --- | --- | --- |
| `schema` | Text | immer `quicktribe.announcement.v1` |
| `id` | UUID | ID der Nachricht, gleich `X-QuickTribe-Delivery`; gleich über alle Wiederholungen |
| `event` | Text | Ereignis-Schlüssel (siehe [Ereignisse](#ereignisse-und-data)) |
| `test` | Boolean | `true` nur bei der Testnachricht (`event` ist dann `integration.test`) |
| `severity` | Text | `info` (Information), `action` (wartet auf das Team) oder `warning` (Warnung) |
| `occurredAt` | Zeitpunkt | wann das Ereignis eintrat, ISO 8601 in UTC |
| `locale` | Text | Sprache von `title`, `text`, `fields[].label` und `link.label`: `de` oder `en` |
| `timezone` | Text | Zeitzone, in der Datumsangaben in `text` und `fields` formatiert sind |
| `community` | Objekt oder `null` | `id`, `slug`, `name` der Community; bei Plattform-Ereignissen die betroffene Community oder `null` |
| `title` | Text | kurzer Titel, z. B. „Neues Mitglied“ |
| `text` | Text | ein Satz zum Ereignis, fertig formuliert in `locale` |
| `fields` | Liste | beschriftete Werte zum Anzeigen: `key` (stabil), `label` (übersetzt), `value` (formatiert, Text) |
| `data` | Objekt | maschinenlesbare Kennwerte – nur IDs, Beträge, Zeitpunkte und Schalter, nie Namen oder E-Mail-Adressen |
| `link` | Objekt oder `null` | `url` (absolut) und `label` der passenden Seite in QuickTribe |

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`

| `event` | `severity` | `data` | `fields[].key` |
| --- | --- | --- | --- |
| `member.joined` | info | `userId`, `via` (`join`, `invite`, `approval`, `checkout`, `plan_approval`) | `member` |
| `member.join_requested` | action | `userId` | `member` |
| `member.left` | info | `userId`, `reason` (`left` = ausgetreten, `plan_ended` = mit dem Plan ausgelaufen) | `member` |
| `plan.subscribed` | info | `userId`, `planId`, `source` (`purchase`, `free`, `grant`); bei Käufen `subscriptionId`, `amountCents`, `currency`, `interval` (`month`, `year`, `once`) | `member`, `plan`, `price` |
| `plan.cancelled` | info | `userId`, `planId`, `subscriptionId`, `endsAt` | `member`, `plan`, `endsAt` |
| `payment.failed` | warning | `userId`, `planId`, `subscriptionId`, `attempt` (Zahl der Versuche laut Stripe), `nextAttemptAt` (falls bekannt) | `member`, `plan`, `nextAttempt` |
| `payment.reversed` | warning | `reason` (`refund`, `dispute`, `dispute_lost`, `dispute_won`), `amountCents`, `currency`; außer bei `dispute_won` auch `full`, `accessRevoked` und – falls zuzuordnen – `userId` | `amount`, `item` |
| `billing.double_purchase` | warning | `userId`, `planId`, `subscriptionId` | `member`, `plan` |
| `plan_application.created` | action | `userId`, `planId`, `applicationId` | `member`, `plan` |
| `form.awaiting_approval` | action | `userId`, `formId`, `submissionId` | `member`, `form` |
| `event.full` | info | `eventId`, `occurrenceStart`, `capacity`, `waitlist` (Warteliste an) | `event`, `startsAt`, `capacity`, `waitlist` |
| `event.cancelled` | warning | `eventId`, `occurrenceStart`, `kind` (`manual` = von Hand, `min_attendees` = Mindestteilnehmerzahl nicht erreicht), `hasReason` (ein Grund wurde angegeben – der Wortlaut wird nie übertragen); von Hand zusätzlich `userId` (wer abgesagt hat), automatisch `minAttendees` und `seatsTaken` (Zusagen zum Stichtag) | `event`, `startsAt`; von Hand `actor`, automatisch `minAttendees`, `seatsTaken` |
| `event.reinstated` | info | `eventId`, `occurrenceStart`, `userId` (wer die Absage zurückgenommen hat) | `event`, `startsAt`, `actor` |
| `affiliate.payout_failed` | warning | `payoutId`, `failedCount` | `failedCount` |
| `integration.test` | info | `channelId`, `sample: true` und Beispielwerte (`userId`, `planId`, `amountCents`, `currency`) | `channel`, `member`, `plan` |

Plattform-Admins bekommen zusätzlich die [Plattform-Ereignisse](/handbuch/plattform-admin/integrationen#ereignisse) im selben Schema.

## Signatur prüfen

QuickTribe berechnet für jeden Zustellversuch:

```text
signature = hex( HMAC-SHA256( signaturschlüssel, t + "." + body ) )
X-QuickTribe-Signature: t=<t>,v1=<signature>
```

`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.

<Note>
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.
</Note>

<CodeGroup>

```php PHP
<?php
// Signaturschlüssel aus QuickTribe, z. B. aus einer Umgebungsvariablen
$secret = getenv('QUICKTRIBE_WEBHOOK_SECRET');
$body = file_get_contents('php://input');               // Rohbody
$header = $_SERVER['HTTP_X_QUICKTRIBE_SIGNATURE'] ?? '';

if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)) {
    http_response_code(400);
    exit('Signatur fehlt');
}
[, $t, $v1] = $m;
if (abs(time() - (int) $t) > 300) {
    http_response_code(400);
    exit('Zeitstempel zu alt');
}
$expected = hash_hmac('sha256', $t.'.'.$body, $secret);
if (!hash_equals($expected, $v1)) {
    http_response_code(401);
    exit('Signatur ungültig');
}

$announcement = json_decode($body, true, 32, JSON_THROW_ON_ERROR);
// Idempotenz: $announcement['id'] bzw. $_SERVER['HTTP_X_QUICKTRIBE_DELIVERY'] merken
http_response_code(204);
```

```js Node.js
// Express: den Body als Buffer lesen, nicht als geparstes JSON
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.QUICKTRIBE_WEBHOOK_SECRET;

app.post('/quicktribe', express.raw({ type: 'application/json' }), (req, res) => {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('X-QuickTribe-Signature') ?? '');
  if (!match) return res.status(400).send('Signatur fehlt');
  const [, t, v1] = match;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.status(400).send('Zeitstempel zu alt');

  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.`).update(req.body).digest();
  const given = Buffer.from(v1, 'hex');
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    return res.status(401).send('Signatur ungültig');
  }

  const announcement = JSON.parse(req.body.toString('utf8'));
  // Idempotenz: announcement.id bzw. req.get('X-QuickTribe-Delivery') merken
  res.sendStatus(204);
});

app.listen(3000);
```

```python Python
# Flask
import hashlib, hmac, json, os, re, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ['QUICKTRIBE_WEBHOOK_SECRET'].encode()

@app.post('/quicktribe')
def quicktribe():
    body = request.get_data()  # Rohbody (bytes)
    m = re.fullmatch(r't=(\d+),v1=([0-9a-f]{64})', request.headers.get('X-QuickTribe-Signature', ''))
    if not m:
        abort(400)
    t, v1 = m.group(1), m.group(2)
    if abs(time.time() - int(t)) > 300:
        abort(400)
    expected = hmac.new(SECRET, t.encode() + b'.' + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, v1):
        abort(401)
    announcement = json.loads(body)
    # Idempotenz: announcement['id'] bzw. request.headers['X-QuickTribe-Delivery'] merken
    return '', 204
```

</CodeGroup>

### 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.

| Antwort | Verhalten von QuickTribe |
| --- | --- |
| `2xx` | zugestellt |
| `3xx` | Weiterleitungen werden nicht verfolgt – zählt als Fehlschlag. Trage die endgültige Adresse ein. |
| `404`, `410` | Der Webhook existiert nicht mehr: Kanal wird **sofort pausiert** (z. B. Zapier bei ausgeschaltetem Zap, Make bei einem deaktivierten Webhook, n8n bei unveröffentlichtem Workflow) |
| `429`, `5xx`, Zeitüberschreitung, Verbindungsfehler | vorübergehend: neuer Versuch nach 10 Sekunden, 1 Minute und 10 Minuten. Ein `Retry-After`-Header (Sekunden oder Datum) wird beachtet, höchstens 1 Stunde. |
| andere `4xx` (z. B. `400`, `401`, `403`) | kein neuer Versuch, zählt als Fehlschlag |

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](/handbuch/owner/integrationen/uebersicht#status-pausieren-und-fortsetzen).

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`](/konfiguration#integrationen) freigeben. Freigegebene Hosts dürfen auch `http://` und andere Ports nutzen.
