Webhooks – So automatisieren Sie Perkstar-Ereignisse mit Echtzeit-API-Benachrichtigungen
Erfahren Sie, wie Sie Webhooks für die Ereignisautomatisierung in Echtzeit konfigurieren. Vollständiger Leitfaden zum Erstellen von Webhook-Endpunkten, zum Abonnieren von Ereignistypen, zum Empfangen von JSON-Nutzlasten, zum Implementieren der Sicherheitsüberprüfung, zum Testen von Lieferungen und zum Beheben von Webhook-Problemen.
Übersicht
Webhooks ermöglichen eine ereignisgesteuerte Automatisierung in Echtzeit, indem sie bei Auftreten bestimmter Ereignisse sofortige Benachrichtigungen von Perkstar an Ihre eigenen Systeme oder Anwendungen von Drittanbietern senden. Im Gegensatz zu herkömmlichen Integrationen, die Änderungen nach einem Zeitplan abfragen, senden Webhooks Daten sofort an Sie, wenn etwas passiert, und ermöglichen so sofortige Reaktionen und nahtlose Automatisierung.
Was Sie mit Webhooks tun können:
Erhalten Sie Echtzeitbenachrichtigungen, wenn Kunden Aktionen durchführen (Registrieren, Karte hinzufügen, Kauf tätigen)
Lösen Sie automatisierte Workflows in Ihren eigenen Systemen basierend auf Treueereignissen aus
Synchronisieren Sie Treuedaten sofort mit benutzerdefinierten Anwendungen oder Datenbanken
Erstellen Sie erweiterte Integrationen mit Plattformen, die nicht nativ unterstützt werden
Erstellen Sie eine benutzerdefinierte Geschäftslogik, die auf Aktivitäten im Treueprogramm reagiert
Überwachen Sie alle Treueereignisse in Echtzeit für Analysen oder Warnungen
Tipp: Webhooks eliminieren Verzögerungen und manuelle Arbeit, indem sie Informationen an Ihre Systeme übertragen, sobald Ereignisse auftreten. Anstatt jede Stunde oder jeden Tag nach Updates zu suchen, erhalten Ihre Anwendungen sofortige Benachrichtigungen und ermöglichen so eine sofortige Kundeneinbindung, Echtzeitberichte und synchronisierte Systeme in Ihrem gesamten Unternehmenstechnologie-Stack.
Wer sollte Webhooks verwenden:
Entwickler: Erstellen benutzerdefinierter Integrationen und Automatisierung
Technische Teams: Implementierung einer erweiterten Workflow-Automatisierung
IT-Administratoren: Anbindung von Perkstar an proprietäre Systeme
Fortgeschrittene Benutzer: Erstellen benutzerdefinierter Geschäftslogik über Standardintegrationen hinaus
Erforderliche technische Kenntnisse:
Verständnis von HTTP/HTTPS und REST-APIs
Möglichkeit, JSON-Daten zu empfangen und zu analysieren
Grundlegende Programmierkenntnisse (jede Sprache, die HTTP-Anfragen verarbeitet)
Zugriff auf einen Webserver oder eine Cloud-Funktion zum Empfang von Webhook-Aufrufen
Bevor Sie beginnen
Anforderungen:
Aktives Perkstar-Konto
Kontoinhaber- oder Administratorberechtigungen
Webhook-Unterstützung in Ihrem Abonnementplan enthalten (siehe Abschnitt „Plan“)
Technische Kenntnisse über APIs und Webentwicklung
Was Sie brauchen:
Technische Infrastruktur:
Ein öffentlich zugänglicher HTTPS-Endpunkt (URL) zum Empfangen von Webhook-Daten
Webserver, Cloud-Funktion oder Webhook-Dienst (Zapier, Make, n8n)
Möglichkeit zum Parsen von JSON-Nutzlasten
(Empfohlen) Überprüfung der Webhook-Signatur aus Sicherheitsgründen
Entwicklungsaufbau:
Die Testumgebung ist von der Produktion getrennt
Protokollierungssystem zur Verfolgung eingehender Webhooks
Fehlerbehandlung und Wiederholungslogik
Überwachen von Warnungen für Webhook-Fehler
Webhooks vs. Integrationen verstehen
Webhooks:
Push-Benachrichtigungen in Echtzeit
Sie schreiben benutzerdefinierten Code, um Ereignisse zu verarbeiten
Maximale Flexibilität und Individualisierung
Erfordert technische Umsetzung
Perfekt für: Benutzerdefinierte Systeme, einzigartige Arbeitsabläufe, Echtzeitanforderungen
Vorgefertigte Integrationen:
Vorkonfigurierte Verbindungen zu beliebten Plattformen
Keine Codierung erforderlich
Beschränkt auf verfügbare Integrationen
Einfachere Einrichtung, aber weniger flexibel
Perfekt für: Standardanwendungsfälle, technisch nicht versierte Benutzer, gängige Plattformen
Verwenden Sie Webhooks, wenn:
Sie benötigen Ereignisbenachrichtigungen in Echtzeit
Sie integrieren benutzerdefinierte oder proprietäre Systeme
Vorgefertigte Integrationen erfüllen nicht Ihre Anforderungen
Sie möchten die vollständige Kontrolle über die Datenverarbeitung
Sie erstellen erweiterte Automatisierungsworkflows
Zugriff auf den Abschnitt „Webhooks“.
So navigieren Sie zu Webhooks
Von Ihrem Bedienoberfläche aus:
Melden Sie sich bei Ihrem Perkstar-Konto an
Klicken Sie im linken Menü auf Einstellungen (⚙️-Symbol).
Klicken Sie oben im Einstellungsbildschirm auf die Registerkarte Webhooks
Hinweis: Auf dem Bildschirm „Webhooks“ werden alle Webhook-Verwaltungstools und -Optionen angezeigt.
Webhooks-Bildschirmlayout
Der Abschnitt „Webhooks“ enthält zwei Hauptbereiche:
Webhooks-Liste (Tabelle):
Zeigt alle vorhandenen Webhooks an
Zeigt URL, Status und Ereignisanzahl für jeden Webhook an
Schneller Überblick über alle aktiven Webhook-Konfigurationen
Schaltfläche „Webhook hinzufügen“:
Erstellt neue Webhook-Konfigurationen
Öffnet das Popup-Fenster zur Webhook-Erstellung
Die Webhooks-Liste verstehen
Webhooks-Tabellenspalten
Alle konfigurierten Webhooks werden in einer Tabelle mit den folgenden Informationen angezeigt:
URL:
Der Endpunkt, der Webhook-Benachrichtigungen empfängt
Vollständige HTTPS-Adresse Ihres empfangenden Servers oder Dienstes
Beispiel: https://api.yourcompany.com/webhooks/perkstar
Status:
Aktueller Betriebsstatus des Webhooks
Aktiviert: Webhook ist aktiv und sendet Benachrichtigungen
Deaktiviert: Der Webhook ist angehalten und sendet keine Benachrichtigungen
Ermöglicht Ihnen, Webhooks vorübergehend zu deaktivieren, ohne sie zu löschen
Ereignisanzahl:
Anzahl der Ereignistypen, die dieser Webhook abonniert hat
Höhere Zahl = Webhook empfängt mehr Arten von Benachrichtigungen
Klicken Sie auf Webhook, um zu sehen, welche spezifischen Ereignisse aktiviert sind
Webhook-Details anzeigen
So zeigen Sie einen vorhandenen Webhook an oder bearbeiten ihn:
Suchen Sie den Webhook in der Webhooks-Liste
Klicken Sie auf die Webhook-Zeile
Das Popup-Fenster mit den Webhook-Details wird geöffnet und zeigt die vollständige Konfiguration an
Gezeigte Details:
Vollständige URL
Alle abonnierten Veranstaltungstypen mit Kontrollkästchen
Aktueller Status (Aktiviert/Deaktiviert umschalten)
Erstellungsdatum
Letzte Lieferinformationen (falls verfügbar)
Optionen zum Bearbeiten und Löschen
Erstellen eines neuen Webhooks
Schritt 1: Bereiten Sie Ihren Endpunkt vor
Warnung: Bevor Sie einen Webhook in Perkstar erstellen, stellen Sie sicher, dass Ihr empfangender Endpunkt bereit ist.
Ihr Endpunkt muss:
Über HTTPS (nicht HTTP) öffentlich zugänglich sein
Akzeptieren Sie HTTP-POST-Anfragen
Geben Sie den Statuscode 200 für den erfolgreichen Empfang zurück
Antworten Sie innerhalb von 5-10 Sekunden (schnelle Bearbeitung)
JSON-Anfragetext analysieren
Behandeln Sie Webhook-Wiederholungsversuche ordnungsgemäß
Sicherheitsempfehlungen:
Verwenden Sie HTTPS (aus Sicherheitsgründen erforderlich)
Webhook-Signaturen validieren (sofern von Perkstar bereitgestellt)
Setzen Sie eine Ratenbegrenzung ein, um Missbrauch zu verhindern
Protokollieren Sie alle eingehenden Webhooks zum Debuggen
Verwenden Sie nach Möglichkeit Firewall-Regeln, um den Zugriff einzuschränken
Beispiel für die Endpunkteinrichtung (Node.js/Express):
Schritt 2: Erstellen Sie den Webhook in Perkstar
So fügen Sie einen neuen Webhook hinzu:
Navigieren Sie zur Registerkarte „Einstellungen“ → „Webhooks“.
Klicken Sie auf die Schaltfläche Webhook hinzufügen
Das Popup-Fenster „Webhook hinzufügen“ wird geöffnet
Schritt 3: Webhook-Einstellungen konfigurieren
Geben Sie die Webhook-URL ein:
Geben Sie im URL-Feld oben im Popup Ihre Endpunktadresse ein
Muss eine vollständige HTTPS-URL sein
Beispiel: https://api.yourcompany.com/webhooks/perkstar
Überprüfen Sie noch einmal, ob sich Tippfehler eingeschlichen haben – falsche URLs schlagen fehl
Wählen Sie Veranstaltungstypen aus:
Unter dem URL-Feld sehen Sie eine Liste der verfügbaren Ereignistypen
Für jeden Ereignistyp gibt es ein Kontrollkästchen
Aktivieren Sie das Kontrollkästchen für jedes Ereignis, das Sie erhalten möchten
Abonnieren Sie nur Veranstaltungen, die Sie tatsächlich benötigen (reduziert unnötigen Datenverkehr)
Schritt 4: Aktivieren Sie den Webhook
Webhook-Status festlegen:
Suchen Sie im Popup nach der Schaltfläche zum Umschalten des Status
Auf Aktiviert umschalten (Position EIN)
Wenn Sie den Webhook speichern, aber noch nicht aktivieren möchten, lassen Sie ihn deaktiviert
Aktivierte Webhooks:
Beginnen Sie sofort mit dem Versenden von Benachrichtigungen
Wird bei allen auftretenden abonnierten Ereignissen ausgelöst
Kann später ohne Löschen deaktiviert werden
Deaktivierte Webhooks:
Die Konfiguration wird gespeichert, aber es werden keine Benachrichtigungen gesendet
Nützlich zum Testen oder für vorübergehende Pausen
Kann jederzeit aktiviert werden
Schritt 5: Speichern Sie den Webhook
So schließen Sie die Webhook-Erstellung ab:
Überprüfen Sie alle Einstellungen (URL, Ereignisse, Status)
Klicken Sie unten im Popup auf die Schaltfläche „Webhook hinzufügen“.
Der Webhook wird erstellt und zur Webhooks-Liste hinzugefügt
Infos: Wenn diese Option aktiviert ist, beginnt der Webhook sofort mit dem Senden von Benachrichtigungen.
Nach der Erstellung:
Der neue Webhook wird in der Webhook-Listentabelle angezeigt
Die Spalte „Ereignisanzahl“ zeigt die Anzahl der abonnierten Ereignisse
In der Statusspalte wird „Aktiviert“ oder „Deaktiviert“ angezeigt
Testen Sie den Webhook, indem Sie ein abonniertes Ereignis auslösen
Verfügbare Ereignistypen
Ereignistypen verstehen
Infos: Ereignistypen stellen bestimmte Aktionen oder Änderungen dar, die in Ihrem Perkstar-Konto stattfinden. Wenn Sie einen Ereignistyp abonnieren, erhält Ihr Webhook jedes Mal eine Benachrichtigung, wenn dieses Ereignis eintritt.
Häufige Ereignistypen
Kundenveranstaltungen:
Kunden.created – Neuer Kunde registriert sich oder wird hinzugefügt
Kunden.updated – Änderungen der Kundenprofilinformationen
Kunden.deleted – Der Kunde wurde aus dem System entfernt
Treuekarten-Events:
card.installed – Der Kunde fügt der digitalen Geldbörse eine Karte hinzu
card.updated – Karteninformationen oder Designänderungen
card.deleted – Der Kunde entfernt die Karte aus der Brieftasche
Transaktionsereignisse:
transaction.created – Punkte, Stempel oder Rückvergütung hinzugefügt
transaction.completed – Transaktion abgeschlossen und bestätigt
transaktion.reversed – Transaktion storniert oder Punkte abgezogen
Belohnungsereignisse:
reward.issued – Der Kunde erhält eine Belohnung
reward.redeemed – Der Kunde nutzt/beansprucht eine Prämie
reward.expired – Nicht beanspruchte Belohnung läuft ab
Push-Benachrichtigungsereignisse:
push.sent – Push-Benachrichtigung an den Kunden gesendet
push.opened – Der Kunde öffnet die Push-Benachrichtigung
push.failed – Die Zustellung der Push-Benachrichtigung ist fehlgeschlagen
Rückmeldung-Events:
Rückmeldung.received – Der Kunde gibt Rückmeldung oder Bewertung ab
Rückmeldung.updated – Rückmeldung wurde geändert
Empfehlungsereignisse:
referral.created – Neue Empfehlung initiiert
referral.completed – Empfehlung wurde erfolgreich konvertiert
Hinweis: Die verfügbaren Veranstaltungstypen können je nach Plan und Perkstar-Version variieren. Sehen Sie sich das Popup-Fenster „Webhook hinzufügen“ an, um die vollständige Liste der für Ihr Konto verfügbaren Ereignisse anzuzeigen.
Auswählen, welche Veranstaltungen Sie abonnieren möchten
Best Practices für die Veranstaltungsauswahl:
Minimal beginnen:
Abonnieren Sie nur Veranstaltungen, die Sie aktiv benötigen
Weniger Ereignisse = einfachere Logik und weniger zu verarbeitende Daten
Sie können später jederzeit weitere Ereignisse hinzufügen
Gängige Startkombinationen:
Verfolgung der Kundenaktivitäten: Kunde.erstellt, Transaktion.abgeschlossen
CRM-Synchronisierung in Echtzeit: kunde.erstellt, kunde.aktualisiert, transaktion.erstellt
Belohnungsautomatisierung: Belohnung.ausgestellt, Belohnung.eingelöst
Engagement-Überwachung: Karte.installiert, Push.geöffnet, Rückmeldung.erhalten
Berücksichtigen Sie das Veranstaltungsvolumen:
„transaction.created“ kann mehrmals am Tag ausgelöst werden (hohes Volumen)
Kunden.created löst seltener aus (geringeres Volumen)
Stellen Sie sicher, dass Ihr System das erwartete Webhook-Volumen verarbeiten kann
Gruppenbezogene Veranstaltungen:
Tipp: Wenn Sie ein Lebenszyklusereignis benötigen, benötigen Sie häufig das komplette Set. Beispiel: Kunden.created, Kunden.updated, Kunden.deleted zusammen. Dadurch wird sichergestellt, dass Ihr System mit allen Änderungen synchronisiert bleibt.
Struktur der Webhook-Nutzlast
Welche Daten werden gesendet?
Infos: Wenn ein Ereignis auftritt, sendet Perkstar eine HTTP-POST-Anfrage an Ihre Webhook-URL, die JSON-Daten über das Ereignis enthält.
Standard-Nutzlaststruktur:
Allgemeine Nutzlastfelder
event_type (Zeichenfolge):
Gibt an, welches Ereignis aufgetreten ist
Beispiel: „Kunden.created“, „transaction.completed“
Verwenden Sie dies, um Webhooks an entsprechende Handler weiterzuleiten
event_id (Zeichenfolge):
Eindeutiger Bezeichner für dieses bestimmte Ereignis
Verwendung für Idempotenz (Erkennung doppelter Lieferungen)
Zur Fehlerbehebung in Protokolle aufnehmen
Zeitstempel (ISO 8601 Datum/Uhrzeit):
Wann das Ereignis aufgetreten ist
Beispiel: „2025-10-14T15:30:00Z“
UTC-Zeitzone
account_id (Zeichenfolge):
Ihre Perkstar-Kontokennung
Nützlich, wenn ein Endpunkt mehrere Konten verwaltet
Kann zum Weiterleiten an die richtige Datenbank/den richtigen Mandanten verwendet werden
Daten (Objekt):
Veranstaltungsspezifische Details
Die Struktur variiert je nach Veranstaltungstyp
Enthält die eigentliche Nutzlast (Kundeninformationen, Transaktionsdetails usw.)
Beispielnutzlasten nach Ereignistyp
Kunde.erstellt:
transaktion.abgeschlossen:
Belohnung.ausgegeben:
Umgang mit Webhook-Payloads
Best Practices für die Nutzlastverarbeitung:
Payload-Struktur validieren:
Überprüfen Sie, ob erforderliche Felder vorhanden sind
Überprüfen Sie, ob die Datentypen korrekt sind
Behandeln Sie fehlende oder unerwartete Felder ordnungsgemäß
Verwenden Sie event_id für Idempotenz:
Speichern Sie verarbeitete Ereignis-IDs, um Duplikate zu erkennen
Wenn Sie dieselbe event_id zweimal erhalten, überspringen Sie die Verarbeitung
Verhindert doppelte Aktionen (doppelte Abrechnung, doppelte Datensätze)
Analysieren Sie die Daten sorgfältig:
Verwenden Sie den für Ihre Sprache geeigneten JSON-Parser
Parsing-Fehler behandeln (fehlerhaftes JSON)
Validieren Sie Daten, bevor Sie sie in der Geschäftslogik verwenden
Reagieren Sie schnell:
Warnung: Geben Sie den Status 200 sofort nach Erhalt zurück. Webhook asynchron verarbeiten (Warteschlange zur Verarbeitung). Führen Sie keine langen Operationen aus, bevor Sie antworten. Perkstar wird es erneut versuchen, wenn Sie nicht schnell reagieren.
Beispiel für eine Idempotenzprüfung (Pseudocode):
Testen Sie Ihre Webhooks
Warum Tests von entscheidender Bedeutung sind
Bevor Sie sich in der Produktion auf Webhooks verlassen:
Stellen Sie sicher, dass Ihr Endpunkt Webhooks korrekt empfängt
Stellen Sie sicher, dass das Parsen der Nutzlast wie erwartet funktioniert
Stellen Sie sicher, dass Ihre Geschäftslogik Ereignisse ordnungsgemäß verarbeitet
Identifizieren und beheben Sie alle Probleme, bevor sie sich auf Kunden auswirken
Teststrategien
1. Verwenden Sie Webhook-Testtools:
Webhook.site: Kostenloser Dienst, der eingehende Webhooks anzeigt
RequestBin: Temporärer Endpunkt zum Überprüfen von Webhook-Nutzlasten
Postman: Testanfragen manuell an Ihren Endpunkt senden
2. Testveranstaltungen in Perkstar erstellen:
Registrieren Sie einen Testkunden
Führen Sie eine Testtransaktion durch
Lösen Sie Ereignisse aus, die Sie abonniert haben
Überprüfen Sie, ob Webhooks an Ihrem Endpunkt ankommen
3. Überprüfen Sie Ihre Protokolle:
Überprüfen Sie die Serverprotokolle auf eingehende POST-Anfragen
Überprüfen Sie die JSON-Nutzlaststruktur
Suchen Sie nach Parsing-Fehlern
Bestätigen Sie, dass die Geschäftslogik ordnungsgemäß ausgeführt wird
4. Fehlerszenarien testen:
Was passiert, wenn Ihr Endpunkt ausfällt?
Wie geht Ihr System mit fehlerhaften Payloads um?
Funktioniert Idempotenz (doppelte event_id senden)?
Kann sich Ihr System nach vorübergehenden Ausfällen erholen?
Verwenden von Webhook.site zum Testen
Schnelltest vor der Produktion:
Gehen Sie zu https://webhook.site
Kopieren Sie die bereitgestellte eindeutige URL
Erstellen Sie in Perkstar einen Test-Webhook mit dieser URL
Abonnieren Sie eine Veranstaltung wie Kunden.created
Erstellen Sie einen Testkunden in Perkstar
Überprüfen Sie webhook.site – Sie sehen die Webhook-Nutzlast
Überprüfen Sie die JSON-Struktur und die Datenfelder
Vorteile:
Keine Codierung erforderlich
Sehen Sie Webhooks in Echtzeit
Überprüfen Sie Header und Nutzlast
Perfekt, um die Nutzlaststruktur vor dem Bau zu verstehen
Vorhandene Webhooks verwalten
Bearbeiten eines Webhooks
So ändern Sie einen vorhandenen Webhook:
Navigieren Sie zur Registerkarte „Einstellungen“ → „Webhooks“.
Klicken Sie in der Liste auf den Webhook, den Sie bearbeiten möchten
Das Popup-Fenster mit den Webhook-Details wird geöffnet
Nehmen Sie Ihre Änderungen vor:
Aktualisieren Sie die URL, wenn sich der Endpunkt geändert hat
Aktivieren oder deaktivieren Sie Ereignistypen
Status umschalten (Aktivieren/Deaktivieren)
Klicken Sie auf die Schaltfläche Speichern oder Aktualisieren
Infos: Änderungen werden sofort wirksam.
Wann Webhooks bearbeitet werden sollten:
Änderungen der Endpunkt-URL (neuer Server, anderer Dienst)
Sie benötigen zusätzliche Ereignistypen
Sie möchten Veranstaltungen auf eine geringere Lautstärke reduzieren
Zur Wartung vorübergehend deaktiviert
Webhooks aktivieren und deaktivieren
So deaktivieren Sie einen Webhook vorübergehend:
Klicken Sie auf den Webhook in der Liste
Stellen Sie den Statusschalter auf „Deaktiviert“.
Klicken Sie auf Speichern
Hinweis: Die Webhook-Konfiguration bleibt erhalten, es werden jedoch keine Benachrichtigungen gesendet.
So aktivieren Sie einen Webhook erneut:
Klicken Sie auf den Webhook
Schalten Sie den Status auf „Aktiviert“ um
Klicken Sie auf Speichern
Tipp: Webhook beginnt sofort mit dem Senden von Benachrichtigungen.
Anwendungsfälle zum Deaktivieren:
Endpunktwartung oder Serveraktualisierungen
Beheben von Webhook-Problemen
Vorübergehende Pause während des Tests
Saisonale Geschäftsschließung
Vorteile vs. Löschen:
Konfiguration bleibt erhalten (URL, Ereignisse)
Später einfach wieder zu aktivieren
Es ist keine Neukonfiguration von Grund auf erforderlich
Kann mehrmals deaktiviert/aktiviert werden
Einen Webhook löschen
So entfernen Sie einen Webhook dauerhaft:
Klicken Sie auf den Webhook in der Liste
Suchen Sie im Detail-Popup nach der Schaltfläche „Löschen“.
Bestätigen Sie den Löschvorgang, wenn Sie dazu aufgefordert werden
Webhook wird aus der Liste entfernt
Nach dem Löschen:
Webhook sendet sofort keine Benachrichtigungen mehr
Konfiguration kann nicht wiederhergestellt werden (muss neu erstellt werden)
Endpoint erhält keine Anfragen mehr von Perkstar
Betrifft keine anderen Webhooks
Wann Webhooks gelöscht werden sollten:
Der Endpunkt ist endgültig außer Betrieb
Integrationsprojekt abgesagt
Webhook wurde nur zu Testzwecken erstellt
Konsolidierung mehrerer Webhooks zu einem
Vor dem Löschen:
Exportieren Sie die Webhook-Konfiguration zur Dokumentation
Benachrichtigen Sie Teammitglieder, die sich möglicherweise auf Webhook verlassen
Stellen Sie sicher, dass keine kritischen Arbeitsabläufe vom Webhook abhängig sind
Erwägen Sie die Deaktivierung zunächst, um die Auswirkungen zu testen, bevor Sie sie endgültig löschen
Best Practices für die Sicherheit
HTTPS-Anforderungen
Warnung: Verwenden Sie immer HTTPS, niemals HTTP. HTTP-Webhooks senden Daten unverschlüsselt über das Internet. Jeder kann sensible Kundendaten abfangen und lesen. Perkstar erfordert möglicherweise HTTPS für alle Webhooks.
HTTPS einrichten:
Nutzen Sie Cloud-Anbieter mit integriertem HTTPS (AWS, Azure, Google Cloud)
Holen Sie sich ein kostenloses SSL-Zertifikat von Let's Encrypt
Verwenden Sie Webhook-Dienste, die HTTPS-Endpunkte bereitstellen
Stellen Sie niemals Produktions-Webhooks über HTTP bereit
Überprüfung der Webhook-Signatur
Infos: Perkstar fügt möglicherweise eine kryptografische Signatur in Webhook-Header ein, sodass Sie überprüfen können, ob der Webhook tatsächlich von Perkstar stammt und nicht gefälscht ist.
Warum es wichtig ist:
Verhindert, dass Angreifer gefälschte Webhooks an Ihren Endpunkt senden
Stellt die Datenintegrität sicher (Webhook wurde während der Übertragung nicht geändert)
Erforderlich für die Verarbeitung sensibler Aktionen (Zahlungen, Kontoänderungen)
So überprüfen Sie (Pseudocode):
Sehen Sie sich die Perkstar-Dokumentation an:
Name des Signatur-Headers
Verwendeter Hashing-Algorithmus (typisch HMAC-SHA256)
Wo finde/konfiguriere ich das Webhook-Geheimnis?
Beispiel-Verifizierungscode für Ihre Sprache
Zugangskontrolle
Endpunktzugriff einschränken:
Verwenden Sie Firewallregeln, um IPs zu begrenzen, die auf Ihren Webhook-Endpunkt zugreifen können
Ratenbegrenzung implementieren (Missbrauch verhindern, wenn URL entdeckt wird)
Zusätzlich zur Signaturüberprüfung sind Authentifizierungsheader erforderlich
Protokollieren Sie alle Webhook-Anfragen zur Sicherheitsüberwachung
Geben Sie keine sensiblen Daten preis:
Fügen Sie keine API-Schlüssel oder Passwörter in Webhook-URLs ein
Verwenden Sie den POST-Text für Daten, nicht für URL-Abfrageparameter
Stellen Sie sicher, dass Fehlermeldungen keine Systeminformationen preisgeben
Bereinigen Sie Protokolle, um vertrauliche Kundendaten zu entfernen
Fehlerbehandlung und Protokollierung
Umfangreiche Protokollierung:
Protokollieren Sie alle eingehenden Webhooks mit Zeitstempel und Ereignis-ID
Nutzlast zum Debuggen aufzeichnen (Datenschutz beachten)
Ergebnisse der Protokollverarbeitung (Erfolg, Fehler, Fehler)
Richten Sie Benachrichtigungen für wiederholte Webhook-Fehler ein
Anmutige Fehlerbehandlung:
Erfassen und protokollieren Sie alle Fehler während der Webhook-Verarbeitung
Geben Sie 200 zurück, auch wenn die Geschäftslogik fehlschlägt (Empfang bestätigen)
Verwenden Sie die Warteschlange für unzustellbare Nachrichten für fehlgeschlagene Webhook-Verarbeitung
Wiederholen Sie fehlgeschlagene Vorgänge mit exponentiellem Backoff
Beispielhafte Fehlerbehandlung:
Erweiterte Webhook-Muster
Mehrere Webhooks für unterschiedliche Zwecke
Sie können mehrere Webhooks mit unterschiedlichen Konfigurationen erstellen.
Beispielarchitektur:
Webhook 1: Kundenereignisse → Synchronisierung mit CRM (Kunde.erstellt, Kunde.aktualisiert)
Webhook 2: Transaktionsereignisse → Aktualisiert das Buchhaltungssystem (transaction.completed)
Webhook 3: Alle Ereignisse → Wird an die Analyseplattform gesendet (alle Ereignistypen)
Webhook 4: Belohnungsereignisse → Löst den Erfüllungsworkflow aus (reward.issued, reward.redeemed)
Vorteile:
Trennung von Anliegen (verschiedene Systeme behandeln unterschiedliche Ereignisse)
Unabhängiger Fehler (der Ausfall eines Webhooks wirkt sich nicht auf andere aus)
Einfacheres Debuggen und Überwachen
Unterschiedliche Sicherheit/Authentifizierung pro Webhook
Fan-Out-Muster
Tipp: Senden Sie Webhooks zur Verteilung an die Nachrichtenwarteschlange. Ihr Webhook-Endpunkt empfängt Perkstar-Webhooks und veröffentlicht sie in der Nachrichtenwarteschlange (RabbitMQ, AWS SQS usw.). Mehrere Verbraucher verarbeiten Ereignisse unabhängig voneinander.
Vorteile:
Skalierbarkeit (mehrere Worker verarbeiten Webhooks)
Zuverlässigkeit (Speichert Ereignisse in die Warteschlange, wenn Verbraucher ausfallen)
Flexibilität (neue Verbraucher hinzufügen, ohne den Webhook zu ändern)
Entkopplung (Webhook-Empfang getrennt von der Verarbeitung)
Webhook-Wiederholungslogik
Webhook-Bereitstellung verstehen:
Perkstar kann fehlgeschlagene Webhooks automatisch wiederholen
Es kommt zu Wiederholungsversuchen, wenn Ihr Endpunkt nicht den Status 200 zurückgibt
Wiederholungszeitpunkt: normalerweise sofort, 1 Minute, 5 Minuten, 30 Minuten
Nach der maximalen Anzahl an Wiederholungsversuchen wird der Webhook möglicherweise als fehlgeschlagen markiert
Ihr Endpunkt sollte:
Bringe schnell 200 zurück (unter 5 Sekunden)
Behandeln Sie doppelte Lieferungen ordnungsgemäß (Idempotenz)
Verlassen Sie sich nicht auf die synchrone Verarbeitung
Webhooks für die asynchrone Verarbeitung in die Warteschlange stellen
Häufige Anwendungsfälle
Echtzeit-CRM-Synchronisierung
Ziel: Halten Sie Ihr CRM stets über die Aktivität Ihres Treueprogramms auf dem Laufenden
Einrichtung:
Abonnieren Sie: Kunden.created, Kunden.updated, Transaction.completed
Webhook sendet Daten an die CRM-API
Kundendatensätze bleiben in Echtzeit synchronisiert
Vorteile:
Das Vertriebsteam erkennt die Loyalitätsaktivitäten sofort
Kein manueller Datenexport/-import
Vollständige Kundensicht über Systeme hinweg
Individuelle Prämienerfüllung
Ziel: Belohnungen außerhalb von Perkstar automatisch erfüllen
Einrichtung:
Abonnieren Sie: Belohnung.issued, Belohnung.redeemed
Webhook löst das Fulfillment-System aus (elektronische Post mit Code senden, Versandauftrag erstellen usw.)
Bestätigung an Perkstar zurückgesendet
Vorteile:
Sofortige Prämienzustellung
Integration mit externen Systemen (E-Geschenkkarten, Versand-APIs)
Automatisierte Arbeitsabläufe reduzieren manuelle Arbeit
Business-Intelligence-Dashboards
Ziel: Echtzeit-Analyse-Bedienoberfläche mit Loyalitätskennzahlen
Einrichtung:
Abonnieren: Alle Veranstaltungstypen
Webhook sendet Daten an die Analysedatenbank
Bedienoberfläche fragt die Datenbank nach Live-Metriken ab
Vorteile:
Echtzeit-Einblick in die Leistung von Treueprogrammen
Benutzerdefinierte Berichte, die über die integrierte Analyse von Perkstar hinausgehen
Kombinieren Sie Treuedaten mit anderen Geschäftskennzahlen
Automatisierung der Kundenbindung
Ziel: Lösen Sie personalisiertes Werbung auf Basis des Loyalitätsverhaltens aus
Einrichtung:
Abonnieren Sie: „transaktion.abgeschlossen“, „belohnung.ausgestellt“, „Rückmeldung.received“.
Webhook löst Werbung-Automatisierungsplattform aus
Personalisierte Folgenachrichten werden automatisch versendet
Vorteile:
Sofortige Reaktion auf Kundenaktionen
Persönliches Engagement verbessert die Loyalität
Der automatisierte Workflow spart dem Marketingteam Zeit
Fehlerbehebung bei Webhooks
Webhook empfängt keine Ereignisse
Problem: Sie haben einen Webhook erstellt, aber es kommen keine Benachrichtigungen an
Schritte zur Fehlerbehebung:
Überprüfen Sie, ob der Webhook aktiviert ist:
Überprüfen Sie die Spalte „Status“ in der Webhooks-Liste
Öffnen Sie die Webhook-Details, um zu bestätigen, dass die Statusumschaltung aktiviert ist
Aktivieren, wenn es deaktiviert ist
Überprüfen Sie, ob die URL korrekt ist:
Öffnen Sie die Webhook-Details und überprüfen Sie die URL
Stellen Sie sicher, dass keine Tippfehler oder zusätzlichen Leerzeichen enthalten sind
Bestätigen Sie, dass es sich um den richtigen Endpunkt handelt (nicht um Localhost oder interne URL).
Endpunkt-Zugänglichkeit testen:
Verwenden Sie Curl oder Postman, um eine Test-POST-Anfrage an Ihre URL zu senden
Stellen Sie sicher, dass der Endpunkt öffentlich zugänglich ist
Überprüfen Sie, ob die Firewall Anfragen von Perkstar-IPs blockiert
Testereignis auslösen:
Führen Sie manuell eine Aktion aus, die das abonnierte Ereignis auslösen soll
Beispiel: Wenn Sie Kunden.created abonniert haben, erstellen Sie einen Testkunden
Überprüfen Sie, ob der Webhook an Ihrem Endpunkt ankommt
Überprüfen Sie die Veranstaltungsabonnements:
Öffnen Sie die Webhook-Details
Stellen Sie sicher, dass Sie die Kontrollkästchen für die gewünschten Ereignisse aktiviert haben
Die Ereignisanzahl sollte mit der erwarteten Anzahl übereinstimmen
Endpunkt gibt Fehler zurück
Problem: Webhooks kommen an, aber Ihr Endpunkt gibt 4xx- oder 5xx-Statuscodes zurück
Häufige Ursachen und Lösungen:
Ungültige JSON-Analyse:
Stellen Sie sicher, dass Ihr Code JSON korrekt analysiert
Behandeln Sie fehlerhaftes JSON ordnungsgemäß
Protokollieren Sie die Rohnutzlast zum Debuggen
Authentifizierungs-/Autorisierungsprobleme:
Wenn Ihr Endpunkt eine Authentifizierung erfordert, stellen Sie sicher, dass der Webhook umgangen werden kann oder über Anmeldeinformationen verfügt
Überprüfen Sie, ob die Logik zur Signaturprüfung korrekt ist
Suchen Sie nach abgelaufenen Token oder Zertifikaten
Timeout-Fehler:
Ihr Endpunkt muss innerhalb von 5–10 Sekunden antworten
Webhooks asynchron verarbeiten (sofort 200 zurückgeben, dann verarbeiten)
Verwenden Sie die Nachrichtenwarteschlange für Vorgänge mit langer Laufzeit
Interne Serverfehler:
Überprüfen Sie Ihre Anwendungsprotokolle auf Fehlerdetails
Beheben Sie Fehler im Webhook-Verarbeitungscode
Fügen Sie eine umfassende Fehlerbehandlung und -protokollierung hinzu
Doppelte Webhook-Zustellungen
Problem: Dasselbe Ereignis wurde mehrmals zugestellt
Ursachen:
Ihr Endpunkt hat 200 nicht schnell genug zurückgegeben (Perkstar hat es erneut versucht)
Netzwerkprobleme führten zu einem erneuten Versuch
Dies ist normales Verhalten – Webhooks sollten idempotent sein
Lösung: Idempotenz mit event_id implementieren:
Für dauerhafte Speicherung:
Speichern Sie event_ids in der Datenbank
Überprüfen Sie die Datenbank vor der Verarbeitung
TTL für gespeicherte Ereignis-IDs festlegen (nach 30 Tagen löschen)
Bei den Webhook-Nutzlasten fehlen die erwarteten Daten
Problem: Der Webhook kommt an, enthält aber keine benötigten Felder
Fehlerbehebung:
Nutzlaststruktur prüfen:
Protokollieren Sie die gesamte Nutzlast, um zu sehen, was tatsächlich gesendet wird
Vergleichen Sie mit der erwarteten Struktur
Stellen Sie sicher, dass Sie im richtigen verschachtelten Objekt suchen
Überprüfen Sie den Ereignistyp:
Unterschiedliche Ereignisse haben unterschiedliche Nutzlaststrukturen
Stellen Sie sicher, dass Sie die richtige Veranstaltung für die von Ihnen benötigten Daten abonnieren
Sehen Sie sich die Perkstar-Dokumentation für Nutzlastschemata an
Behandeln Sie null/fehlende Felder:
Möglicherweise sind nicht alle Felder in allen Veranstaltungen vorhanden
Implementieren Sie Nullprüfungen in Ihrem Code
Verwenden Sie Standardwerte für optionale Felder
API-Version:
Die Struktur der Webhook-Nutzlast kann je nach API-Version variieren
Überprüfen Sie, ob Sie ein Upgrade durchführen oder die Version ändern müssen
Wenden Sie sich für die Nutzlastdokumentation an den Support
Zusammenfassung der Best Practices
Checkliste für die Webhook-Implementierung
Sicherheit:
✅ Verwenden Sie nur HTTPS-Endpunkte
✅ Implementieren Sie die Überprüfung der Webhook-Signatur
✅ Beschränken Sie den Zugriff mit Firewall-Regeln
✅ Legen Sie niemals API-Schlüssel in Webhook-URLs offen
✅ Protokollieren Sie alle Webhooks zur Sicherheitsüberprüfung
Zuverlässigkeit:
✅ Geben Sie den Status 200 sofort zurück (unter 5 Sekunden)
✅ Webhooks asynchron verarbeiten
✅ Implementieren Sie Idempotenz mit event_id
✅ Verwenden Sie die Nachrichtenwarteschlange für eine robuste Verarbeitung
✅ Richten Sie eine Überwachung und Alarmierung bei Ausfällen ein
Leistung:
✅ Empfang schnell bestätigen (Rückgabe 200)
✅ Webhooks für die Hintergrundverarbeitung in die Warteschlange stellen
✅ Horizontal skalieren, wenn das Webhook-Volumen hoch ist
✅ Verwenden Sie gegebenenfalls Caching
✅ Optimieren Sie Datenbankabfragen in Webhook-Handlern
Testen:
✅ Testen Sie vor der Produktion mit webhook.site
✅ Erstellen Sie Test-Webhooks in einer separaten Umgebung
✅ Überprüfen Sie, ob die Idempotenz ordnungsgemäß funktioniert
✅ Fehlerszenarien und Wiederherstellung testen
✅ Überwachen Sie Test-Webhooks während der ersten Einführung
Wartung:
✅ Dokumentieren Sie alle Webhooks und ihre Zwecke
✅ Überprüfen Sie die Webhook-Protokolle regelmäßig
✅ Deaktivieren Sie nicht verwendete Webhooks, um Lärm zu reduzieren
✅ Aktualisieren Sie Endpunkt-URLs, wenn sich die Infrastruktur ändert
✅ Webhook-Abonnements vierteljährlich prüfen
Häufig gestellte Fragen
Was ist der Unterschied zwischen Webhooks und dem API-Schlüssel?
Mit dem API-Schlüssel können Sie die API von Perkstar aufrufen, um Daten anzufordern oder Aktionen auszuführen. Webhooks senden Daten automatisch an Sie, wenn Ereignisse auftreten. API = Sie ziehen Daten. Webhooks = Perkstar überträgt Daten an Sie.
Kann ich mehrere Webhooks mit derselben URL haben?
Ja, aber normalerweise ist es unnötig. Sie können einen Webhook erstellen, der mehrere Ereignistypen abonniert. Mehrere Webhooks zu derselben URL können zu doppelten Zustellungen führen, wenn sich Ereignisabonnements überschneiden.
Was passiert, wenn mein Endpunkt ausfällt?
Perkstar wird die Zustellung im Laufe von Minuten bis Stunden mehrmals wiederholen. Wenn alle Wiederholungsversuche fehlschlagen, wird der Webhook möglicherweise als fehlgeschlagen markiert. Sie müssen es erneut aktivieren und verpassen möglicherweise Ereignisse während der Ausfallzeit. Verwenden Sie aus Gründen der Zuverlässigkeit eine Nachrichtenwarteschlange.
Wie kann ich Webhooks testen, ohne die Produktionsdaten zu beeinträchtigen?
Verwenden Sie ein Test-/Sandbox-Perkstar-Konto, falls verfügbar, oder erstellen Sie Testkunden/Transaktionen, die deutlich als Tests gekennzeichnet sind. Sie können webhook.site auch verwenden, um Nutzlasten zu überprüfen, bevor Sie Ihren Endpunkt erstellen.
Kann ich ein Protokoll der gesendeten Webhooks sehen?
Webhook-Zustellungsprotokolle sind möglicherweise in der Webhook-Detailansicht verfügbar und zeigen die letzten Zustellungen, Zeitstempel und den Erfolgs-/Fehlerstatus an. Überprüfen Sie die Detailseite jedes Webhooks auf den Lieferverlauf.
Was soll ich tun, wenn ich zu viele Webhooks erhalte?
Melden Sie sich von Ereignistypen ab, die Sie nicht benötigen, oder implementieren Sie eine Filterung in Ihrem Endpunkt, um bestimmte Ereignisse zu ignorieren. Sie können Webhooks auch stapelweise verarbeiten, anstatt sie einzeln zu bearbeiten.
Kann ich Localhost-URLs zum Testen verwenden?
Nein. Localhost-URLs (http://localhost:3000) sind nicht öffentlich zugänglich. Verwenden Sie ngrok, webhook.site oder stellen Sie es zum Testen in einem Cloud-Dienst mit einer öffentlichen URL bereit.
Woher weiß ich, welche Veranstaltungen ich abonnieren sollte?
Beginnen Sie mit den Mindestereignissen, die für Ihren Anwendungsfall erforderlich sind. Gemeinsamer Ausgangspunkt: „Kunden.created“ und „transaction.completed“. Sie können später jederzeit weitere Ereignisse hinzufügen, wenn sich die Anforderungen ändern.
Was ist die maximale Nutzlastgröße für Webhooks?
Webhook-Nutzlasten sind normalerweise klein (unter 10 KB), da sie präzise Ereignisdaten und keine großen Dateien enthalten. Wenn Sie eine vollständige Kundenhistorie benötigen, verwenden Sie Webhooks, um API-Aufrufe auszulösen, die detaillierte Daten abrufen.
Können Webhooks Daten an interne (private Netzwerk-)Endpunkte senden?
Nein. Webhooks erfordern öffentlich zugängliche HTTPS-URLs. Verwenden Sie für interne Systeme einen öffentlich zugänglichen Proxy oder API-Gateway, der sicher an interne Systeme weiterleitet.
Wie schnell werden Webhooks nach einem Ereignis bereitgestellt?
Webhooks werden in der Regel innerhalb von Sekunden nach Eintreten des Ereignisses übermittelt. Der genaue Zeitpunkt hängt von der Systemauslastung ab. Unter normalen Bedingungen ist jedoch mit einer Bereitstellung nahezu in Echtzeit zu rechnen.
Was passiert, wenn ich einen Webhook für ein Ereignis erhalte, das ich nicht kenne?
Protokollieren Sie die gesamte Nutzlast zur Untersuchung. Möglicherweise fügt Perkstar neue Veranstaltungstypen hinzu oder Sie haben versehentlich Veranstaltungen abonniert. Überprüfen Sie das Feld „event_type“ und vergleichen Sie es mit der Dokumentation.
Kann ich Webhooks nach Kundensegment oder Kartentyp filtern?
Auf der Webhook-Abonnementebene ist die Filterung normalerweise nicht verfügbar. Sie erhalten Webhooks für alle Ereignisse abonnierter Typen und müssen Ihren Endpunktcode basierend auf Nutzlastdaten filtern.
Wie aktualisiere ich meine Webhook-URL, ohne die Konfiguration zu verlieren?
Bearbeiten Sie den vorhandenen Webhook, ändern Sie die URL und speichern Sie. Alle Ereignisabonnements und Einstellungen bleiben erhalten. Die neue URL empfängt sofort zukünftige Webhooks.
Sind Webhooks in allen Plänen enthalten?
Die Verfügbarkeit von Webhooks hängt von Ihrem Abonnementplan ab. Sehen Sie im Abschnitt „Plan“ nach, ob Webhooks enthalten sind und wie viele Sie erstellen können. Höherstufige Pläne bieten in der Regel mehr Webhooks.
Tipp: Benötigen Sie weitere Hilfe? Wenden Sie sich an den Perkstar-Support für Webhook-Fehlerbehebung, Payload-Dokumentation, Implementierungsanleitungen oder technische Fragen zu Ereignistypen und -zustellung.