JeriCommerce erfasst alle wichtigen Interaktionen von Kunden mit Ihrem Treueprogramm. Wenn Sie die Custom-API-Integration verbinden, werden alle Ereignisse als HTTP-POST-Webhooks an Ihren konfigurierten Endpunkt gesendet. So können Sie eigene Automatisierungen erstellen, Daten synchronisieren oder Workflows in beliebigen Systemen auslösen.

Einrichtung

Fügen Sie Ihren Webhook-Endpunkt unter Settings → Integrations → API hinzu, schalten Sie die Funktion Events ein und speichern Sie. Ab diesem Zeitpunkt wird jedes infrage kommende Kundenereignis als POST-Anfrage an Ihre URL gesendet.

Authentifizierung

Jede Anfrage enthält einen Header x-jericommerce-hmac-sha256 mit einer HMAC-SHA256-Signatur, die mit dem auf der Integrationsseite angezeigten geheimen Schlüssel erstellt wurde. Überprüfen Sie die Signatur auf Ihrem Server, um die Herkunft der Anfrage von JeriCommerce zu bestätigen und Spoofing zu verhindern.

Der Ereignistyp wird im Header x-jericommerce-event-type gesendet. Verwenden Sie ihn, um den Payload an den passenden Handler weiterzuleiten.

Zustellfehler und Wiederholungen

Netzwerkfehler sowie Antworten 408, 429 und 5xx werden mit exponentiell steigenden Wartezeiten bis zu 10-mal erneut versucht. Dauerhafte Clientfehler wie 401, 403, 404 und 410 führen sofort zum Abbruch und werden nicht erneut versucht. Machen Sie Ihren Endpunkt idempotent, da bei vorübergehenden Fehlern dasselbe Ereignis mehrmals zugestellt werden kann.

JeriCommerce zählt für jede API-Integration aufeinanderfolgende dauerhafte Fehler. Nach 10 dauerhaften Fehlern wird Events für diese Integration ausgeschaltet, damit keine weiteren Anfragen an einen nicht funktionierenden Endpunkt gesendet werden. Beheben Sie den Fehler und schalten Sie anschließend Events in den API-Integrationseinstellungen wieder ein. Eine erfolgreiche Zustellung setzt den Zähler aufeinanderfolgender Fehler zurück.

Basis-Payload

Alle Webhooks verwenden dieselbe Grundstruktur:

{
  "email": "customer@example.com",
  "id": "event-uuid",
  "customerId": "customer-uuid",
  "campaignId": "campaign-uuid",
  "url": "https://...",
  "browser": "Chrome 120",
  "createdAt": "2026-03-08T12:00:00Z",
  "properties": { ... }
}

Die folgenden optionalen Felder sind möglicherweise nicht bei jedem Ereignis vorhanden:

  • campaignId — nur wenn das Ereignis mit einer bestimmten Kampagne verknüpft ist
  • url und browser — nur bei Ereignissen aus dem Web

Alle Ereignisse

Unten finden Sie die vollständige Liste der 19 Ereignisse, die an Ihren Webhook gesendet werden. Die Spalte Event name entspricht dem Wert im Header x-jericommerce-event-type. Key properties zeigt die Felder im Objekt properties des jeweiligen Ereignisses.

Event name Auslöser Wichtige Eigenschaften
Customer
Customer created Ein neuer Kunde wird registriert (nicht bei der Erstsynchronisierung) email, origin, referral, utmCampaign, utmMedium, utmSource, firstName, lastName, phoneNumber
Customer birthday Ein geplanter täglicher Prozess prüft Kunden-Geburtstage (läuft etwa um 9:00 Uhr UTC) age (aus dem Geburtsdatum berechnet)
Customer scanned Ein Kunde scannt über Shopify POS einen NFC-Code an einem physischen Standort Standort- und Gerätekontext
Customer tapped Ein Kunde hält sein Gerät an ein VTAP-/NFC-Gerät Gerätekontext
Wallet pass
Wallet pass requested Ein Kunde fordert einen Downloadlink für einen Wallet-Pass an email, referral, downloadLink, utmCampaign, utmSource, utmMedium
Wallet pass installed Ein Kunde fügt den Pass zu Apple Wallet oder Google Wallet hinzu referral, utmCampaign, utmSource, utmMedium
Wallet pass uninstalled Ein Kunde entfernt den Pass aus seinem Wallet referral, utmCampaign, utmSource, utmMedium
Loyalty
Balance changed Treuepunkte werden hinzugefügt oder abgezogen (Käufe, Erstattungen, manuelle Anpassungen) amount, reference, previous (Punktestand vor der Änderung), pointsToNextReward, nextRewardName
Tier changed Die Stufe eines Kunden ändert sich (Neuberechnung täglich um 5:00 Uhr oder bei Änderung des Punktestands) previous (Stufenname), current (Stufenname)
Coupons
Coupon assigned Einem Kunden wird ein Couponcode zugewiesen code, header, body, slug, assignedFrom, installUrl
Coupon expiring Ein zugewiesener, ungenutzter Couponcode läuft am nächsten Kalendertag in der Zeitzone des Shops ab couponId, couponCodeId, couponSlug, code, expiresAt
Coupon pass installed Ein Kunde fügt einen Coupon-Pass zu Apple Wallet oder Google Wallet hinzu referral, utmCampaign, utmSource, utmMedium
Coupon pass uninstalled Ein Kunde entfernt einen Coupon-Pass aus seinem Wallet referral, utmCampaign, utmSource, utmMedium
Gift cards
Gift card sent Der Admin sendet einem Kunden eine Geschenkkarte code, header, body, slug, assignedFrom, installUrl, mailSent
Rewards
Reward redeemable Eine Prämie kann von einem Kunden eingelöst werden rewardId, rewardLink, rewardTitle, rewardValue, rewardCost, customerRemainingBalance
Reward redeemed Ein Kunde löst eine Prämie ein rewardId, rewardLink, rewardTitle, code
Reward refunded Der Admin erstattet eine zuvor eingelöste Prämie claimId
Engagement
Wallet click Ein Kunde klickt auf einen Link auf seinem Wallet-Pass url, browser, utmCampaign, utmSource ("wallet"), utmMedium ("wallet_pass")
Wallet visit Ein Kunde besucht oder öffnet die Web-App des Wallet-Passes name, url, browser, referral, utmCampaign, utmSource, utmMedium

Damit ist alles eingerichtet. Ihr Endpunkt erhält nun in Echtzeit Daten zu allen Kundeninteraktionen mit JeriCommerce.

Coupon expiring

Das Ereignis Coupon expiring ist über die allgemeine API-Ereigniszuordnung verfügbar. Es wird für einen Kunden zugewiesen, aber noch nicht verwendeten Couponcode ausgelöst, der am nächsten Kalendertag nach der Zeitzone des Shopify-Shops abläuft. Kann JeriCommerce die Zeitzone nicht abrufen, wird UTC verwendet. Es handelt sich nicht um eine Erinnerung exakt 24 Stunden vor Ablauf.

Zu properties des Ereignisses gehören couponId, couponCodeId, couponSlug, code und expiresAt. Verwenden Sie das Ereignis für eigene Automatisierungen. Es sendet nicht automatisch eine E-Mail oder Push-Benachrichtigung und ist kein Shopify-Flow-Auslöser.