Eingehende Webhooks

📥 Eingehende Webhooks

Erhalten Sie automatisch Ereignisse von externen Plattformen und vergeben Sie Samen an Ihre Kunden. Eingehende Webhooks ermöglichen es Ihnen, jedes Drittanbieter-Tool — Quiz-Apps, Formulare, Bewertungsplattformen, Zapier, Make und mehr — mit Ihrem LoyaltyTree-Loyalitätsprogramm zu verbinden.

So funktioniert es

Das System der eingehenden Webhooks verwendet ein Quellen- & Codes-Modell:

1. Erstellen Sie eine Quelle — Eine Quelle repräsentiert eine externe Plattform oder ein Tool (z.B. "Typeform", "Zapier", "Meine Quiz-App"). Jede Quelle erhält eine eindeutige Webhook-URL und einen geheimen Schlüssel zur Sicherheit.
2. Fügen Sie Codes zur Quelle hinzu — Jeder Code definiert eine spezifische Aktion, die Samen vergibt (z.B. "quiz_completed", "form_submitted", "birthday_claimed"). Sie legen fest, wie viele Samen jeder Code vergibt, mit optionalen Limits.
3. POST-Anfragen senden — Ihre externe Plattform sendet eine POST-Anfrage an die Webhook-URL mit dem Code und den Kundeninformationen. LoyaltyTree findet oder erstellt den Kunden und vergibt die Samen automatisch.

Erste Schritte

Schritt 1: Erstellen Sie eine Webhook-Quelle

Navigieren Sie zu Stores → [Ihr Geschäft] → Integrationen → Eingehende Webhooks. Klicken Sie auf + Quelle hinzufügen und geben Sie ihr einen Namen, der die externe Plattform beschreibt (z.B. "Typeform-Quiz" oder "Zapier-Automatisierung").

Wenn die Quelle erstellt wurde, erhalten Sie:

• Webhook-URL — Der Endpunkt, an den Ihre externe Plattform Anfragen sendet
• Webhook-Geheimnis — Ein geheimer Schlüssel zum Signieren von Anfragen (empfohlen zur Sicherheit)

Schritt 2: Codes hinzufügen

Jeder Code repräsentiert eine spezifische Aktion, die Sie belohnen möchten. Klicken Sie auf + Code hinzufügen in Ihrer Quelle, um einen zu erstellen.

Feld	Erforderlich	Beschreibung
Code	Ja	Der genaue Wert, der im Webhook-Payload gesendet wird (z.B. quiz_completed). Dies muss mit dem übereinstimmen, was Ihre externe Plattform sendet.
Anzeigename	Ja	Ein benutzerfreundlicher Name, der im Admin-Dashboard und in der Transaktionshistorie angezeigt wird (z.B. "Quiz abgeschlossen").
Beschreibung	Nein	Eine optionale Notiz für Ihr Team, wann dieser Code verwendet wird.
Anzahl der Samen	Ja	Wie viele Samen bei jeder Auslösung dieses Codes vergeben werden. Standardmäßig 1.
Max. Samen/Kunde	Nein	Die maximale Gesamtzahl an Samen, die ein einzelner Kunde von diesem Code verdienen kann. Leer lassen für unbegrenzt. Sobald ein Kunde dieses Limit erreicht, werden weitere Webhook-Anrufe für ihn erfolgreich zurückgegeben, aber 0 Samen vergeben.
Cooldown (Stunden)	Nein	Minimale Stunden zwischen Auszeichnungen für denselben Kunden bei diesem Code. Verhindert Missbrauch, indem die Häufigkeit, mit der ein Kunde Samen verdienen kann, begrenzt wird. Leer lassen für keinen Cooldown.
Aktiviert	—	Umschalten, um diesen Code zu aktivieren oder zu deaktivieren, ohne ihn zu löschen. Deaktivierte Codes geben einen 403-Fehler zurück.

Codes & Limits erklärt

Codes und ihre Limits arbeiten zusammen, um Ihnen präzise Kontrolle darüber zu geben, wie Samen vergeben werden:

Anzahl der Samen

Jeder Code hat eine feste Anzahl an Samen. Jedes Mal, wenn der Webhook mit diesem Code ausgelöst wird, erhält der Kunde genau so viele Samen. Wenn Sie beispielsweise "quiz_completed" auf 5 Samen setzen, vergibt jeder qualifizierte Webhook-Aufruf 5 Samen.

Max. Samen pro Kunde

Dies setzt ein Lebenszeitlimit pro Kunde pro Code. Es sind die insgesamt Samen, die dieser Kunde von diesem spezifischen Code verdienen kann, nicht die Anzahl der Male, die er ihn auslösen kann.

Cooldown (Stunden)

Setzt eine minimale Wartezeit zwischen Samenvergaben für denselben Kunden bei demselben Code. Der Cooldown-Timer beginnt nach der letzten erfolgreichen Vergabe.

Request Format

Sendet eine POST-Anfrage an Ihre Webhook-URL mit folgendem JSON-Body:

{
  "code": "your_code_here",
  "customer": {
    "email": "customer@example.com",
    "shopify_customer_id": "12345",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* Mindestens eines von email oder shopify_customer_id ist erforderlich. E-Mail ist erforderlich, wenn der Kunde noch nicht in LoyaltyTree existiert.

HMAC-Signaturverifizierung (empfohlen)

Um zu überprüfen, dass die Anfragen tatsächlich von Ihrer Plattform kommen (und nicht von jemandem, der Ihre Webhook-URL gefunden hat), signieren Sie Ihre Anfragen mit HMAC-SHA256.

Unterstützte Signatur-Header (LoyaltyTree überprüft alle diese):

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

Der Signaturwert kann entweder der rohe hex-Hash oder mit sha256= vorangestellt sein (beide Formate werden akzeptiert).

Alternative: Plain Token-Authentifizierung

Wenn HMAC-Signierung in Ihrer Plattform nicht möglich ist, können Sie Ihr Webhook-Geheimnis als einfachen Token im X-Token-Header übergeben. LoyaltyTree vergleicht es direkt mit Ihrem Geheimnis.

Beispiel: Signieren mit Node.js

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'quiz_completed',
  customer: { email: 'jane@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'your_webhook_secret')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

Beispiel: Signieren mit Python

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "quiz_completed",
    "customer": {"email": "jane@example.com"}
})
signature = hmac.new(
    b'your_webhook_secret',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

Beispiel: Verwendung von cURL (zum Testen)

curl -X POST https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "X-Token: your_webhook_secret" \
  -d '{"code":"quiz_completed","customer":{"email":"jane@example.com"}}'

Antwortformat

Erfolgreiche Antwort (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

Erfolgreich, aber begrenzt (200)

Wenn ein Cooldown oder ein Maximal-Samen-Limit die Vergabe verhindert, erhalten Sie dennoch eine 200-Antwort, jedoch mit 0 Samen und einer Erklärung:

{
  "success": true,
  "seeds_awarded": 0,
  "message": "Cooldown aktiv. Versuchen Sie es in 18 Stunde(n) erneut."
}

// oder
{
  "success": true,
  "seeds_awarded": 0,
  "message": "Maximale Samen (15) bereits für diesen Code vergeben."
}

Fehlerantworten

Anwendungsbeispiele

Verbindung mit Zapier

Zapier ist eine der beliebtesten Möglichkeiten, LoyaltyTree mit Hunderten anderer Apps zu verbinden. Wir bauen eine dedizierte LoyaltyTree-Integration im Zapier App Store, die die Einrichtung noch einfacher macht — suchen Sie danach im Zapier-Marktplatz.

In der Zwischenzeit können Sie die Aktion Webhooks von Zapier verwenden, um sofort zu verbinden:

Verbindung mit Make (Integromat)

Sie können auch das Modul HTTP / Make a request von Make verwenden, um Webhooks an LoyaltyTree zu senden. Konfigurieren Sie es auf die gleiche Weise wie Zapier — setzen Sie die URL, fügen Sie den JSON-Body mit code und customer hinzu und fügen Sie Ihr Geheimnis im X-Token-Header ein.

Webhook-Protokolle

Jeder eingehende Webhook-Aufruf wird protokolliert und ist im Abschnitt Eingehende Webhooks Ihrer Integrationsseite sichtbar. Die Protokolle zeigen:

• Zeitstempel – Wann der Webhook empfangen wurde
• Quelle – Welche Quelle ihn empfangen hat
• Status – Erfolg oder Misserfolg
• Details – Verwendeter Code, vergebene Samen oder Fehlermeldung
• Payload – Der gesamte Anfrage-Body (verschlüsselt im Ruhezustand)

Verwenden Sie die Protokolle, um zu überprüfen, ob Ihre Integration korrekt funktioniert und um Probleme zu beheben.

Fehlerbehebung

Sicherheit

• Jede Quelle erhält ein einzigartiges 64-Zeichen-Webhooks-Geheimnis, das automatisch generiert und im Ruhezustand verschlüsselt ist
• Geheimnisse können jederzeit aus den Quelleneinstellungen neu generiert werden (das alte Geheimnis funktioniert sofort nicht mehr)
• Anfrage-Payloads sind in den Protokollen verschlüsselt für die Privatsphäre
• Die Signaturverifizierung verwendet zeit-sicheren Vergleich, um Timing-Angriffe zu verhindern
• Quellen und Codes können einzeln deaktiviert werden, ohne sie zu löschen