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 machen 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 Treueprogrammaktivitäten 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
Technische Kenntnisse erforderlich:
Verständnis der HTTP/HTTPS und REST APIs
Fähigkeit, JSON-Daten zu empfangen und zu analysieren
Grundlegende Programmierkenntnisse (jede Sprache, die HTTP-Anfragen verarbeitet)
Zugriff auf einen Webserver oder eine Cloud-Funktion zum Empfangen 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
Entwicklungs-Einrichtung:
Die Testumgebung ist von der Produktion getrennt
Protokollierungssystem zur Verfolgung eingehender Webhooks
Fehlerbehandlung und Wiederholungslogik
Überwachungswarnungen für Webhook-Fehler
Webhooks vs. Integrationen verstehen
Webhooks:
Push-Benachrichtigungen in Echtzeit
Sie schreiben benutzerdefinierten Code zur Verarbeitung von Ereignissen
Maximale Flexibilität und Anpassung
Erfordert technische Implementierung
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 Webhooks-Abschnitt
So navigieren Sie zu Webhooks
Von Ihrem Übersicht 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: Der Webhooks-Bildschirm zeigt alle Webhook-Verwaltungstools und -Optionen an.
Webhooks-Bildschirmlayout
Der Webhooks-Bereich 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 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: Der -Webhook ist aktiv und sendet Benachrichtigungen
deaktiviert: 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 den 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 „
Webhook-Details“ wird geöffnet und zeigt die vollständige Konfiguration an
Angezeigte Details:
Vervollständigen Sie URL
Alle abonnierten Ereignistypen 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:
Öffentlich zugänglich sein über HTTPS (nicht HTTP)
Akzeptieren Sie HTTP POST-Anfragen
Gibt den Statuscode 200 für den erfolgreichen Empfang zurück
Antworten Sie innerhalb von 5-10 Sekunden (schnelle Verarbeitung)
JSON-Anfragetext analysieren
Webhook-Wiederholungsversuche ordnungsgemäß verarbeiten
Sicherheitsempfehlungen:
Verwenden Sie HTTPS (aus Sicherheitsgründen erforderlich)
Webhook-Signaturen validieren (sofern von Perkstar bereitgestellt)
Implementieren Sie eine Ratenbegrenzung, um Missbrauch zu verhindern
Protokolliert alle eingehenden Webhooks zum Debuggen
Verwenden Sie nach Möglichkeit Firewall-Regeln, um den Zugriff einzuschränken
Beispiel-Endpunkt-Einrichtung (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 den Webhook URL ein:
Geben Sie im Feld URL oben im Popup Ihre Endpunktadresse ein
Muss ein vollständiger HTTPS URL sein
Beispiel: https://api.yourcompany.com/webhooks/perkstar
Überprüfen Sie die Eingabe noch einmal auf Tippfehler – falsche URLs schlagen fehl
Wählen Sie Veranstaltungstypen aus:
Unter dem Feld URL 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 (ON-Position)
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
Info: 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
Info: Ereignistypen stellen bestimmte Aktionen oder Änderungen dar, die in Ihrem Perkstar-Konto auftreten. Wenn Sie einen Ereignistyp abonnieren, erhält Ihr Webhook jedes Mal eine Benachrichtigung, wenn dieses Ereignis eintritt.
Häufige Ereignistypen
Kundenveranstaltungen:
Kunde.created – Neuer Kunde registriert sich oder wird hinzugefügt
Kunde.updated – Änderungen der Kundenprofilinformationen
Kunde.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ückmeldungen-Events:
Rückmeldungen.received – Der Kunde gibt Rückmeldungen oder Bewertung ab
Rückmeldungen.updated – Rückmeldungen wurde geändert
Empfehlungsereignisse:
referral.created – Neue Empfehlung initiiert
referral.completed – Empfehlung wurde erfolgreich konvertiert
Notiz: Die verfügbaren Ereignistypen 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 der zu abonnierenden Ereignisse
Best Practices für die Eventauswahl:
Start minimal:
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:
Kundenaktivitätsverfolgung: Kunde.erstellt, Transaktion.abgeschlossen
Echtzeit-CRM-Synchronisierung: Kunde.erstellt, Kunde.aktualisiert, Transaktion.erstellt
Belohnungsautomatisierung: Belohnung.ausgestellt, Belohnung.eingelöst
Engagement-Überwachung: -Karte.installiert, Push-geöffnet, Rückmeldungen erhalten
Berücksichtigen Sie das Ereignisvolumen: Die erstellte
-Transaktion kann mehrmals am Tag ausgelöst werden (hohes Volumen).
Kunde.created löst seltener aus (geringeres Volumen)
Stellen Sie sicher, dass Ihr System das erwartete Webhook-Volumen verarbeiten kann
Gruppenbezogene Ereignisse:
Tipp: Wenn Sie ein Lebenszyklusereignis benötigen, benötigen Sie häufig das komplette Set. Beispiel: Kunde.created, Kunde.updated, Kunde.deleted zusammen. Dadurch wird sichergestellt, dass Ihr System mit allen Änderungen synchronisiert bleibt.
Webhook-Nutzlaststruktur
Welche Daten werden gesendet
-Info: Wenn ein Ereignis auftritt, sendet Perkstar eine HTTP POST-Anfrage an Ihren Webhook URL mit JSON-Daten zum Ereignis.
Standard-Nutzlaststruktur:
Gemeinsame Payload-Felder
event_type (Zeichenfolge):
Identifiziert, welches Ereignis aufgetreten ist
Beispiel: „Kunde.created“, „transaction.completed“
Verwenden Sie dies, um Webhooks an geeignete Handler weiterzuleiten
event_id (Zeichenfolge):
Eindeutige Kennung 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
Konto-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):
Ereignisspezifische Details Die Struktur von
variiert je nach Ereignistyp
Enthält die eigentliche Nutzlast (Kundeninformationen, Transaktionsdetails usw.)
Beispielnutzlasten nach Ereignistyp
Kunde.erstellt:
-Transaktion.abgeschlossen:
Belohnung.ausgestellt:
Umgang mit Webhook-Nutzlasten
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)
Daten sorgfältig analysieren:
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 antworten.
Beispiel einer Idempotenzprüfung (Pseudocode):
Testen Sie Ihre Webhooks
Warum Tests so wichtig sind
Bevor Sie sich in der Produktion auf Webhooks verlassen:
Überprüfen Sie, ob Ihr Endpunkt Webhooks korrekt empfängt
Stellen Sie sicher, dass das Parsen der Nutzlast wie erwartet funktioniert
Bestätigen Sie, dass Ihre Geschäftslogik Ereignisse ordnungsgemäß verarbeitet
Identifizieren und beheben Sie alle Probleme, bevor sie sich auf Kunden auswirken
-Teststrategien
1. Webhook-Testtools verwenden:
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. Testereignisse in Perkstar erstellen:
Registrieren Sie einen Testkunden
Führen Sie eine Testtransaktion durch
Trigger-Ereignisse, 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 Nutzlaststruktur JSON
Überprüfen Sie, ob Parsing-Fehler vorliegen
Bestätigen Sie, dass die Geschäftslogik korrekt 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?
Verwendung von Webhook.site zum Testen
Schnelltest vor der Produktion:
Gehen Sie zu https://webhook.site
Kopieren Sie das bereitgestellte eindeutige URL
Erstellen Sie in Perkstar einen Test-Webhook mit diesem URL
Abonnieren Sie eine Veranstaltung wie Kunde.created
Erstellen Sie einen Testkunden in Perkstar
Überprüfen Sie webhook.site – Sie sehen die Webhook-Nutzlast
Überprüfen Sie die Struktur und Datenfelder von JSON Vorteile von
:
Keine Codierung erforderlich
Webhooks in Echtzeit anzeigen
Header und Nutzlast prüfen
Perfekt, um die Nutzlaststruktur vor dem Bau zu verstehen
Verwalten vorhandener Webhooks
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 URL, wenn sich der Endpunkt geändert hat
Ereignistypen aktivieren oder deaktivieren
Status umschalten (Aktivieren/Deaktivieren)
Klicken Sie auf die Schaltfläche „Speichern“ oder „Aktualisieren“.
-Info: Änderungen werden sofort wirksam.
Wann Webhooks bearbeitet werden sollten:
Endpunkt URL Änderungen (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
Schalten Sie den Statusschalter auf „Deaktiviert“.
Klicken Sie auf Speichern
Hinweis: Die Webhook-Konfiguration von bleibt erhalten, es werden jedoch keine Benachrichtigungen gesendet.
So aktivieren Sie einen Webhook erneut:
Klicken Sie auf den Webhook
Status auf Aktiviert umschalten
Klicken Sie auf Speichern
Tipp: Webhook beginnt sofort mit dem Senden von Benachrichtigungen.
Anwendungsfälle zum Deaktivieren:
Endpunktwartung oder Serveraktualisierungen
Fehlerbehebung bei Webhook-Problemen
Vorübergehende Pause während des Tests
Saisonale Geschäftsschließung
Vorteile gegenüber dem 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)
Der Endpunkt 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:
Verwenden Sie Cloud-Anbieter mit integriertem HTTPS (AWS, Azure, Google Cloud).
Holen Sie sich das kostenlose 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
Info: Perkstar kann eine kryptografische Signatur in Webhook-Headern enthalten, sodass Sie überprüfen können, ob der Webhook tatsächlich von Perkstar stammt und nicht gefälscht wurde.
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):
Überprüfen Sie die Perkstar-Dokumentation:
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-Körper für Daten, nicht die 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
Beispiel für eine Fehlerbehandlung:
Erweiterte Webhook-Muster
Mehrere Webhooks für unterschiedliche Zwecke
Sie können mehrere Webhooks mit unterschiedlichen Konfigurationen erstellen.
Beispielarchitektur:
Webhook 1: Kundenereignisse → Synchronisiert mit CRM (Kunde.created, Kunde.updated)
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 von
:
Trennung von Belangen (verschiedene Systeme verarbeiten unterschiedliche Ereignisse)
Unabhängiger Fehler (ein Webhook-Fehler wirkt sich nicht auf andere aus)
Einfacheres Debuggen und Überwachen
Unterschiedliche Sicherheit/Authentifizierung pro Webhook
Fan-Out-Muster
Tipp: Webhooks zur Verteilung an die Nachrichtenwarteschlange senden. 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 von
:
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
Wiederholungsversuche finden statt, 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:
200 schnell zurückgeben (unter 5 Sekunden)
Doppelte Lieferungen ordnungsgemäß behandeln (Idempotenz)
Nicht auf synchrone Verarbeitung angewiesen
Webhooks in die Warteschlange für die asynchrone Verarbeitung stellen
Häufige Anwendungsfälle
Echtzeit-CRM-Synchronisierung
Ziel: Halten Sie CRM sofort über die Aktivitäten des Treueprogramms auf dem Laufenden
-Einrichtung:
Abonnieren: Kunde.created, Kunde.updated,transaction.completed
Webhook sendet Daten an CRM API
Kundendatensätze bleiben in Echtzeit synchronisiert Vorteile von
: Das
-Vertriebsteam erkennt die Treueaktivitäten sofort
Kein manueller Datenexport/-import
Vollständige Kundensicht über Systeme hinweg
Benutzerdefinierte Belohnungserfü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 von
:
Sofortige Prämienlieferung
Integration mit externen Systemen (E-Geschenkkarten, Versand APIs)
Automatisierter Workflow reduziert manuelle Arbeit
Business Intelligence-Dashboards
Ziel: Echtzeit-Analyse-Übersicht mit Treuemetriken
-Einrichtung:
Abonnieren: Alle Ereignistypen
Webhook sendet Daten an die Analysedatenbank
Übersicht fragt die Datenbank nach Live-Metriken ab Vorteile von
:
Echtzeit-Einblick in die Leistung des Treueprogramms
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 Kommunikation basierend auf Loyalitätsverhalten aus
-Einrichtung:
Abonnieren Sie: Transaction.Completed, Reward.Issued, Rückmeldungen.Received
Webhook löst Kommunikation-Automatisierungsplattform aus
Personalisierte Folgenachrichten werden automatisch gesendet Vorteile von
:
Sofortige Reaktion auf Kundenaktionen
Personalisiertes Engagement verbessert die Loyalität
Automatisierter 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 Statusspalte in der Webhooks-Liste
Öffnen Sie die Webhook-Details, um zu bestätigen, dass die Statusumschaltung ON ist
Aktivieren, wenn es deaktiviert ist
Überprüfen Sie, ob URL korrekt ist:
Öffnen Sie die Webhook-Details und überprüfen Sie URL
Stellen Sie sicher, dass keine Tippfehler oder zusätzlichen Leerzeichen vorhanden sind
Bestätigen Sie, dass es sich um den richtigen Endpunkt handelt (nicht localhost oder internes URL).
Endpunkt-Zugänglichkeit testen:
Verwenden Sie Curl oder Postman, um eine Test-POST-Anfrage an Ihr URL zu senden
Stellen Sie sicher, dass der Endpunkt öffentlich zugänglich ist
Überprüfen Sie, ob die Firewall Anfragen von Perkstar-IPs blockiert
Ein Testereignis auslösen:
Führen Sie manuell eine Aktion aus, die ein abonniertes Ereignis auslösen soll
Beispiel: Wenn Sie Kunde.created abonniert haben, erstellen Sie einen Testkunden
Überprüfen Sie, ob der Webhook an Ihrem Endpunkt ankommt
Überprüfen Sie die Veranstaltungsabonnements:
Webhook-Details öffnen
Überprüfen Sie, ob Sie die Kontrollkästchen für die gewünschten Ereignisse aktiviert haben Die
-Ereignisanzahl sollte mit der erwarteten Zahl ü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ültiges JSON-Parsing:
Stellen Sie sicher, dass Ihr Code JSON korrekt analysiert
Behandeln Sie fehlerhafte 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)
Nachrichtenwarteschlange für lang andauernde Vorgänge verwenden
Interne Serverfehler:
Überprüfen Sie Ihre Anwendungsprotokolle auf Fehlerdetails
Behebung von Fehlern im Webhook-Verarbeitungscode
Fügen Sie eine umfassende Fehlerbehandlung und -protokollierung hinzu
Doppelte Webhook-Zustellungen
Problem: Dasselbe Ereignis wurde mehrmals übermittelt
Ursachen:
Ihr Endpunkt hat 200 nicht schnell genug zurückgegeben (Perkstar erneut versucht)
Netzwerkprobleme führten zu einem erneuten Versuch
Dies ist normales Verhalten – Webhooks sollten idempotent sein
Lösung: Idempotenz mithilfe von event_id implementieren:
Für dauerhafte Speicherung:
Event_IDs in der Datenbank speichern
Datenbank vor der Verarbeitung prüfen
TTL auf gespeicherte Ereignis-IDs setzen (nach 30 Tagen löschen)
-Webhook-Nutzlasten, bei denen erwartete Daten fehlen
Problem: Webhook kommt an, enthält aber keine benötigten Felder
Fehlerbehebung:
Payload-Struktur prüfen:
Protokollieren Sie die gesamte Nutzlast, um zu sehen, was tatsächlich gesendet wird
Vergleich mit erwarteter Struktur
Stellen Sie sicher, dass Sie im richtigen verschachtelten Objekt suchen
Überprüfen Sie den Ereignistyp:
Verschiedene Ereignisse haben unterschiedliche Nutzlaststrukturen
Stellen Sie sicher, dass Sie das richtige Ereignis für die von Ihnen benötigten Daten abonnieren
Überprüfen Sie die Perkstar-Dokumentation auf Nutzlastschemata
Behandelt null/fehlende Felder:
Möglicherweise sind nicht alle Felder in allen Ereignissen vorhanden
Implementieren Sie Nullprüfungen in Ihrem Code
Standardwerte für optionale Felder verwenden
API-Version: Die Struktur der
-Webhook-Nutzlast kann je nach API-Version variieren
Überprüfen Sie, ob Sie ein Upgrade oder eine Versionsänderung benötigen
Wenden Sie sich für die Nutzlastdokumentation an den Support
Best Practices-Zusammenfassung
Webhook-Implementierungs-Checkliste
Sicherheit:
✅ Verwenden Sie nur HTTPS-Endpunkte
✅ Webhook-Signaturüberprüfung implementieren
✅ 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:
✅ 200-Status sofort zurückgeben (unter 5 Sekunden)
✅ Webhooks asynchron verarbeiten
✅ Idempotenz mit event_id implementieren
✅ Verwenden Sie die Nachrichtenwarteschlange für eine robuste Verarbeitung
✅ Richten Sie die Überwachung und Benachrichtigung bei Fehlern 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
✅ Datenbankabfragen in Webhook-Handlern optimieren
-Test:
✅ Testen Sie vor der Produktion mit webhook.site
✅ Test-Webhooks in einer separaten Umgebung erstellen
✅ Ü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 regelmäßig die Webhook-Protokolle
✅ Deaktivieren Sie nicht verwendete Webhooks, um Lärm zu reduzieren
✅ Aktualisieren Sie die 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 Schlüssel API können Sie 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 sendet Daten an Sie.
Kann ich mehrere Webhooks mit demselben URL haben?
Ja, aber normalerweise ist es unnötig. Sie können einen Webhook erstellen, der mehrere Ereignistypen abonniert. Mehrere Webhooks für dasselbe URL können zu doppelten Zustellungen führen, wenn sich Ereignisabonnements überschneiden.
Was passiert, wenn mein Endpunkt ausfällt?
Perkstar wiederholt die Zustellung innerhalb von Minuten bis Stunden mehrmals. 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?
Nr. Localhost URLs (http://localhost:3000) sind nicht öffentlich zugänglich. Verwenden Sie ngrok, webhook.site oder stellen Sie sie zum Testen in einem Cloud-Dienst mit einem öffentlichen URL bereit.
Woher weiß ich, welche Veranstaltungen ich abonnieren sollte?
Beginnen Sie mit den für Ihren Anwendungsfall erforderlichen Mindestereignissen. Gemeinsamer Ausgangspunkt: „Kunde.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 ein API-Gateway, das sicher an interne Systeme weiterleitet.
Wie schnell werden Webhooks nach einem Ereignis zugestellt?
-Webhooks werden normalerweise innerhalb von Sekunden nach Auftreten 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. Perkstar fügt möglicherweise neue Ereignistypen hinzu oder Sie haben Ereignisse versehentlich abonniert. Überprüfen Sie das Feld „event_type“ und vergleichen Sie es mit der Dokumentation.
Kann ich Webhooks nach Kundensegment oder Kartentyp filtern?
-Filterung ist normalerweise nicht auf der Webhook-Abonnementebene verfügbar. Sie erhalten Webhooks für alle Ereignisse abonnierter Typen und müssen Ihren Endpunktcode basierend auf Nutzlastdaten filtern.
Wie aktualisiere ich meinen Webhook URL, ohne die Konfiguration zu verlieren?
Bearbeiten Sie den vorhandenen Webhook, ändern Sie URL und speichern Sie. Alle Ereignisabonnements und Einstellungen bleiben erhalten. Der neue URL empfängt sofort zukünftige Webhooks.
Sind Webhooks in allen Plänen enthalten? Die Verfügbarkeit des
-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, Nutzlastdokumentation, Implementierungsanleitungen oder technische Fragen zu Ereignistypen und -zustellung.