Webhooks

Webhooks ermöglichen es dir, in Echtzeit über wichtige Ereignisse in deinem Soulclick-System informiert zu werden. Wenn bestimmte Aktionen auftreten, sendet Soulclick automatisch HTTP-POST-Anfragen mit den relevanten Daten an deine konfigurierten Endpunkte.

Unterstützte Events

donation.completed

Wird ausgelöst, wenn eine Spende erfolgreich verarbeitet wurde. Enthält detaillierte Informationen über die Transaktion und die Spenderperson.

Beispiel Payload:

{
  "id": "event-123",
  "event": "donation.completed",
  "created_at": "2024-01-15T10:30:00Z",
  "environment": "prod",
  "data": {
    "donation": {
      "id": "DON-2024-001",
      "created_at": "2024-01-15T10:30:00Z",
      "amount": 50.0,
      "currency": "CHF",
      "campaign": {
        "id": 123,
        "title": "Hilfsprojekt Afrika"
      },
      "purpose": "Unterstützung für Bildungsprojekte",
      "donor": {
        "gender": "male",
        "first_name": "Max",
        "last_name": "Mustermann",
        "email": "[email protected]",
        "company": "Beispiel AG",
        "po_box": null,
        "street": "Musterstrasse",
        "street_number": "123",
        "postal_code": "8000",
        "city": "Zürich",
        "country": "CH",
        "language": "de",
        "newsletter": true
      },
      "payment": {
        "transaction_id": "TXN-ABC123",
        "method": "CC",
        "status": "completed"
      },
      "invoice": null
    }
  }
}

shop_order.completed

Wird ausgelöst, wenn eine Shop-Bestellung erfolgreich abgeschlossen wurde. Unterstützt sowohl registrierte Kund:innen als auch Gastbestellungen.

Beispiel Payload:

{
  "id": "event-456",
  "event": "shop_order.completed",
  "created_at": "2024-01-15T11:00:00Z",
  "environment": "prod",
  "data": {
    "shop_order": {
      "id": "ORDER-2024-001",
      "created_at": "2024-01-15T11:00:00Z",
      "customer": {
        "gender": "female",
        "first_name": "Anna",
        "last_name": "Beispiel",
        "email": "[email protected]",
        "phone": "+41 44 123 45 67",
        "company": "Firma GmbH",
        "department": "Marketing",
        "care_of": null,
        "po_box": null,
        "street": "Beispielweg",
        "street_number": "456",
        "postal_code": "3000",
        "city": "Bern",
        "country": "CH",
        "language": "de"
      },
      "invoice_address": {
        "first_name": "Anna",
        "last_name": "Beispiel",
        "company": "Firma GmbH",
        "department": "Marketing",
        "care_of": null,
        "po_box": null,
        "street": "Beispielweg",
        "street_number": "456",
        "postal_code": "3000",
        "city": "Bern",
        "country": "CH"
      },
      "delivery_address": {
        "first_name": "Anna",
        "last_name": "Beispiel",
        "company": "Firma GmbH",
        "department": "Marketing",
        "care_of": null,
        "po_box": null,
        "street": "Beispielweg",
        "street_number": "456",
        "postal_code": "3000",
        "city": "Bern",
        "country": "CH"
      },
      "items": [
        {
          "article_number": "ART-001",
          "quantity": 2,
          "unit_price_net": 25.0,
          "unit_price_gross": 27.0,
          "discount_percentage": 0,
          "total_price_gross": 54.0
        }
      ],
      "currency": "CHF",
      "total_price_gross": 59.0,
      "total_vat": 4.0,
      "total_discount": 0.0,
      "payment": {
        "transaction_id": "TXN-DEF456",
        "method": "PAYPAL",
        "status": "completed"
      },
      "shipping": {
        "method": "standard",
        "cost": 5.0
      }
    }
  }
}

Konfiguration

Webhook-Endpunkt einrichten

1. Admin Interface: Navigiere zu "Webhook Endpunkte" im Admin-Interface
2. URL: Gib die vollständige URL deines Webhook-Endpunkts ein
3. Status: Aktiviere den Endpunkt durch Setzen von "Aktiv" auf true
4. Authentifizierung (Optional): Konfiguriere die Basic Auth mit Benutzername und Passwort

Sicherheit

• HTTPS: Verwende immer HTTPS-URLs für deine Webhook-Endpunkte
• Basic Authentication: Nutze die integrierten Basic Auth-Funktionen für zusätzliche Sicherheit
• Timeout: Webhook-Anfragen haben ein Timeout von 30 Sekunden

Verhalten und Zuverlässigkeit

Retry-Mechanismus

Soulclick implementiert ein exponentielles Backoff-System für fehlgeschlagene Webhook-Auslieferungen:

Nach 5 fehlgeschlagenen Versuchen wird das Event als "Maximale Wiederholungen erreicht" markiert und nicht mehr versucht.

HTTP-Statuscodes

• 2xx: Event erfolgreich verarbeitet
• Andere: Event wird als fehlgeschlagen markiert und erneut versucht

Verarbeitung

Webhook-Events werden automatisch vom System verarbeitet und an deine konfigurierten Endpunkte gesendet.

Endpunkt-Implementation

Beispiel-Handler (Python/Flask)

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    data = request.get_json()
    
    # Event verarbeiten
    event_type = data.get('event')
    event_data = data.get('data')
    
    if event_type == 'donation.completed':
        # Spende verarbeiten
        donation = event_data.get('donation')
        print(f"Neue Spende: {donation['amount']} {donation['currency']} von {donation['donor']['email']}")
        
    elif event_type == 'shop_order.completed':
        # Shop-Bestellung verarbeiten
        order = event_data.get('shop_order')
        print(f"Neue Bestellung: {order['id']} für {order['total_price_gross']} {order['currency']}")
    
    # Erfolgreiche Verarbeitung bestätigen
    return jsonify({'status': 'success'}), 200

if __name__ == '__main__':
    app.run()

Best Practices

1. Idempotenz: Behandle Events idempotent - dasselbe Event könnte mehrfach gesendet werden
2. Schnelle Antworten: Antworte innerhalb des 30-Sekunden-Timeouts
3. Logging: Protokolliere alle eingehenden Webhooks für Debugging-Zwecke
4. Validation: Validiere die Payload-Struktur bevor du sie verarbeitest
5. Asynchrone Verarbeitung: Für komplexe Verarbeitungslogik verwende bitte Queues

Monitoring und Debugging

Event-Status überwachen

Events können folgende Status haben:

• "Wartend": Wartet auf Verarbeitung
• "Zugestellt": Erfolgreich zugestellt
• "Fehlgeschlagen": Fehlgeschlagen, wird erneut versucht
• "Maximale Wiederholungen erreicht": Maximale Wiederholungen erreicht

Troubleshooting

Events werden nicht gesendet:

• Kontaktiere den Soulclick-Support, um zu überprüfen, ob Webhooks für deine Instanz aktiviert sind
• Stelle sicher, dass ein aktiver Webhook-Endpunkt konfiguriert ist

Events schlagen fehl:

• Überprüfe die Felder "Letzter Response Code" und "Letzter Response Body" im Admin
• Stelle sicher, dass dein Endpunkt erreichbar ist und 2xx-Statuscodes zurückgibt
• Prüfe die Netzwerkverbindung und Firewall-Einstellungen

Performance:

• Events werden automatisch vom System verarbeitet
• Bei anhaltenden Problemen kontaktiere den Soulclick-Support

Datenfelder-Referenz

Donor/Customer-Felder

Payment-Felder

Umgebungen

Das environment-Feld gibt die aktuelle Systemumgebung an:

• "prod": Produktionsumgebung
• "stage": Staging-Umgebung
• "test": Testumgebung

Technische Details

Datenformate

Timestamps:

• Alle Zeitangaben verwenden das ISO 8601 Format mit UTC-Zeitzone
• Beispiel: "2024-01-15T10:30:00Z"

Währungsbeträge:

• Dezimalzahlen mit bis zu 2 Nachkommastellen
• Mindestbetrag: 0.01
• Beispiel: 50 oder 50.5 für CHF 50.00 bzw. CHF 50.50

Länder- und Sprachcodes:

• Ländercodes verwenden ISO 3166-1 alpha-2 (z.B. "CH", "DE", "AT")
• Sprachcodes verwenden ISO 639-1 (z.B. "de", "en", "fr", "it")

Währungscodes:

• ISO 4217 Standard (z.B. "CHF", "EUR", "USD")

Unterstützte Zahlungsmethoden

Die häufigsten Zahlungsmethoden sind:

• "ECA": MasterCard
• "VIS": Visa
• "TWI": Twint
• "PFC": PostFinance Card
• "PEF": PostFinance E-Finance
• "PAP": PayPal
• "INV": Rechnung/Banküberweisung

Eine vollständige Liste aller unterstützten Zahlungsmethoden findest du in der Datatrans-Dokumentation.

Sicherheit und Integration

Empfohlene Sicherheitsmaßnahmen:

• Verwende HTTPS für alle Webhook-Endpunkte
• Implementiere Signaturverifikation (falls verfügbar)
• Validiere alle eingehenden Daten
• Implementiere Idempotenz für Webhook-Verarbeitung

Best Practices:

• Antworte innerhalb von 30 Sekunden
• Verwende HTTP-Statuscode 200-299 für erfolgreiche Verarbeitung
• Logge alle Webhook-Events für Audit-Zwecke
• Implementiere eigene Retry-Logik für kritische Prozesse