Webhooks einrichten

Ein Webhook sendet eine HTTPS-Anfrage von Mateflow an eine URL, die du kontrollierst, sobald in deiner Community etwas passiert, etwa wenn ein neues Mitglied beitritt oder eine Zahlung eingeht. Mit Webhooks hältst du ein CRM, ein E-Mail-Tool oder deine eigene App synchron. Du richtest sie unter Admin → Einstellungen → Integrationen → Webhooks ein.

Wer kann das tun: Inhaber und Administratoren. · Wo: Web (Admin-Konsole). · Tarif: Webhooks und die Anzahl, die du erstellen kannst, hängen von deinem Plattform-Tarif ab.

Webhook-Endpunkt erstellen

1. Gehe zu Admin → Einstellungen → Integrationen und öffne den Tab Webhooks.
2. Klicke auf Webhook hinzufügen.
3. Gib einen Name (unter 100 Zeichen) und die Endpunkt-URL ein. Die URL muss HTTPS verwenden.
4. Optional, aber empfohlen: Klicke unter Secret (optional) auf die Schaltfläche zum Generieren (Secret generieren) und kopiere das Secret für deinen Server. Siehe den Abschnitt zur Signatur weiter unten.
5. Hake unter Ereignisse die Ereignisse an, die gesendet werden sollen. Hake einen Kategorienamen an, um alle Ereignisse dieser Kategorie auszuwählen.
6. Lass Aktiv eingeschaltet, damit der Webhook sofort Ereignisse empfängt.
7. Klicke auf Webhook erstellen.

Wenn die Schaltfläche Webhook hinzufügen einen Upgrade-Hinweis zeigt, enthält dein Tarif keine Webhooks oder du hast das Webhook-Limit deines Tarifs erreicht. Siehe Tarifnutzung und Limits prüfen.

Webhook-Ereignisse, die du abonnieren kannst

Kategorie	Ereignisse
Mitglieder	Mitglied beigetreten, Rolle geändert, Mitglied gesperrt (wird auch bei Bans gesendet), Mitglied wieder aktiviert, Mitglied zu Zugriffsgruppe hinzugefügt, Mitglied aus Zugriffsgruppe entfernt
Inhalte	Beitrag erstellt, Kommentar erstellt, Beitrag gelöscht, Kommentar gelöscht
Zahlungen	Zahlung erhalten, Zahlung fehlgeschlagen, Abo erstellt, Abo verlängert, Abo gekündigt, Rückerstattung ausgestellt

Ältere Webhooks zeigen möglicherweise Ereignisse, die nicht mehr verfügbar sind. Du kannst sie entfernen, aber nicht erneut hinzufügen.

So funktionieren Webhook-Ereignisse für Zugriffsgruppen

Mitglied zu Zugriffsgruppe hinzugefügt und Mitglied aus Zugriffsgruppe entfernt (Zugriffsgruppen hießen früher Mitgliederstufen) werden ausgelöst, wenn sich die Gruppen eines Mitglieds tatsächlich ändern. Jedes Ereignis betrifft ein Mitglied und eine Gruppe und enthält den Benutzernamen und die E-Mail-Adresse des Mitglieds, den Namen der Gruppe und den Grund der Änderung: ein Administrator, ein Abo, eine Einladung, die Standard-Zugriffsgruppe oder eine gelöschte Gruppe.

• Vor Mitglied beigetreten wird kein Zugriffsgruppen-Ereignis gesendet. Die Standardgruppe eines neuen Mitglieds bei der Registrierung wird also nicht gemeldet, ebenso wenig Änderungen, während ein Mitglied auf die Genehmigung wartet.
• Wenn du eine Zugriffsgruppe löschst, wird für jedes Mitglied, das sie hatte, ein Entfernungsereignis gesendet. Diese Ereignisse und Ereignisse durch das Festlegen einer Standardgruppe können einige Minuten später ankommen.
• Wenn du eine Gruppe entfernst, die ein Abo gewährt, werden erst ein Entfernungs- und dann ein Hinzufügungsereignis gesendet, weil das Abo die Gruppe sofort wieder hinzufügt. Siehe Zugriffsgruppe eines Mitglieds hinzufügen oder entfernen.

Webhook-Signaturen mit dem Signaturschlüssel prüfen

Wenn ein Webhook ein Secret hat, signiert Mateflow jede Anfrage mit HMAC-SHA256, damit dein Server prüfen kann, dass sie von Mateflow stammt und nicht verändert wurde (Signaturprüfung). Jede Anfrage enthält zwei Header:

• X-Mateflow-Timestamp: wann die Anfrage gesendet wurde, in Unix-Sekunden.
• X-Mateflow-Signature: sha256=, gefolgt von der hexadezimal codierten Signatur.

So prüfst du eine Anfrage auf deinem Server:

1. Lies den unverarbeiteten Request-Body genau so, wie er empfangen wurde, bevor du das JSON parst.
2. Setze die signierte Zeichenkette zusammen: den Wert von X-Mateflow-Timestamp, einen Punkt (.) und dann den unverarbeiteten Body.
3. Berechne einen HMAC-SHA256 dieser Zeichenkette mit deinem Secret als Schlüssel und codiere ihn hexadezimal.
4. Vergleiche ihn mit dem Teil von X-Mateflow-Signature nach sha256=, und zwar mit einem Vergleich in konstanter Zeit. Weise die Anfrage ab, wenn sie sich unterscheiden.
5. Weise optional Anfragen ab, deren Zeitstempel älter als einige Minuten ist, um Replay-Angriffe zu verhindern.

Während einer Übergangszeit enthalten Anfragen zusätzlich das Secret selbst im Header X-Webhook-Secret. Prüfe die Signatur, statt dich auf diesen Header zu verlassen.

Anfragen aus der Aktion Trigger webhook einer Automatisierungsregel funktionieren anders: Sie sind nicht signiert, und das Secret der Regel wird unverändert im Header X-Webhook-Secret gesendet. Siehe Aufgaben mit Regeln automatisieren.

Nach dem Speichern wird das Secret ausgeblendet. Um es beizubehalten, lass das Feld leer, wenn du den Webhook bearbeitest. Um es zu wechseln, generiere ein neues und aktualisiere gleichzeitig deinen Server.

Webhook testen, pausieren, bearbeiten oder löschen

Im Menü Aktionen des Webhooks:

• Webhook testen sendet eine Testanfrage an deinen Endpunkt.
• Deaktivieren stoppt Zustellungen, ohne den Webhook zu löschen; Aktivieren schaltet ihn wieder ein.
• Bearbeiten ändert Name, URL, Secret oder Ereignisse.
• Löschen entfernt den Webhook und alle seine Zustellprotokolle. Das kann nicht rückgängig gemacht werden.

Die Liste zeigt für jeden Webhook Status, Zuletzt ausgelöst sowie die Anzahl Erfolgreich und Fehlgeschlagen. Ein Webhook zeigt einen Fehlerstatus, wenn die letzten Zustellungen fehlgeschlagen sind.

Webhook-Zustellungen und Wiederholungen prüfen

Öffne den Tab Zustellprotokolle, um jede Anfrage mit HTTP-Status, Dauer und Quelle zu sehen. Klicke auf Details anzeigen, um die vollständige Anfrage-Payload und den Antwort-Body zu sehen. Zustellprotokolle werden 30 Tage lang aufbewahrt.

Wenn eine Zustellung fehlschlägt, versucht Mateflow sie automatisch bis zu 3-mal erneut. Es gibt keine Schaltfläche, um eine Zustellung selbst erneut zu senden. Jeder Versuch erhält eine eigene Zeile und eine neue Zustell-ID, während die Ereignis-ID gleich bleibt. Zeilen mit derselben Ereignis-ID sind also Versuche für dasselbe Ereignis. Zustellungen können mehrfach oder in anderer Reihenfolge ankommen, lass deinen Server daher anhand der Ereignis-ID deduplizieren. Die Felder der Payload findest du in der Entwicklerdokumentation unter mateflow.com/developers.

Verwandte Artikel

• Integrationen im Überblick: API, Webhooks und Zapier
• API-Schlüssel erstellen
• So funktionieren Zugriffsgruppen
• Aufgaben mit Regeln automatisieren