Webhook-Integration
Ein Webhook meldet Kontoereignisse an Ihre Empfangs-URL. Prüfen Sie den maßgeblichen Zustand über GET Transaktion.
Empfänger einrichten
Hinterlegen Sie in Heth eine eigene URL und das Integrationsgeheimnis und aktivieren Sie die Zustellung. Eine URL-Änderung ändert den Empfänger der Kontoereignisse. Schützen Sie den Endpunkt und vermeiden Sie Weiterleitungen an Dritte. Die Konfiguration verlangt eine Nutzersitzung; der Transaktionsschlüssel genügt nicht automatisch.
Mitteilungen verarbeiten
- Kontosignatur und Wiederholungsschutz wie unten beschrieben prüfen.
- Ereignis-/Transaktions-ID ohne sensible Felder protokollieren.
- Idempotent verarbeiten: doppelte oder verspätete Zustellung erzeugt keine weitere Zahlung.
- Transaktion mit eigenen Zugangsdaten abrufen und Status abgleichen.
- Die im Zustellvertrag geforderte Antwort senden.
Browser-Push ist kein Webhook und garantiert keine Zustellung. Diese Übersicht verspricht weder Reihenfolge noch Wiederholungsintervalle noch einen gemeinsamen Authentifizierungsstandard. Klären Sie den tatsächlichen Zustellvertrag vor Produktionsautomatisierung.
Format des Konto-Webhooks
Dieses Format gilt für die in Heth konfigurierten Konto-Webhooks. Andere Callbacks können abweichen.
Bei gesetztem Geheimnis enthalten Anfragen x-webhook-signature (hex HMAC-SHA256), x-webhook-timestamp (Unix-Sekunden) und x-webhook-event-id. HMAC über timestamp + "." + die unveränderten HTTP-Body-Bytes mit dem Geheimnis prüfen; JSON vorher nicht neu serialisieren. Body-Zeitstempel mit Header vergleichen, mehr als 5 Minuten Zeitabweichung ablehnen, Signatur zeitkonstant vergleichen und event_id deduplizieren. Wiederholungen behalten event_id und erhalten neuen Zeitstempel/Signatur. Ohne Geheimnis können Signaturheader fehlen; vor Automatisierung Geheimnis einrichten.
hex(HMAC-SHA256(secret, timestamp + "." + raw_body))
Der Umschlag enthält event_id, timestamp, type und data. Transaktionsdaten enthalten tx_id, txid, type, status, amount, currency und event_type. amount kann ein JSON-Integer sein: verlustfrei parsen. Bei Spenden kann donation hinzukommen. Nach Prüfung und Speicherung HTTP 2xx zurückgeben; wiederholte geprüfte event_id darf keine erneute Geschäftsanweisung auslösen. Transaktion trotzdem per GET prüfen.