Webhooks

Webhooks senden Ereignisse aus dem Shop an externe Systeme. Auf dieser Seite legst du Webhook-Ziele an, steuerst die Authentifizierung und prüfst im Logbuch, welche Webhooks erfolgreich, ausstehend oder fehlgeschlagen sind.

Voraussetzungen

Die Webhook-Verwaltung steht zur Verfügung, wenn die App REST API & Webhooks aktiv ist und der Benutzer das Recht für den Zugriff auf Webhooks besitzt. Ist die App nicht aktiv, zeigt das Backend einen Hinweis zur Aktivierung an.

Reiter Einstellungen

Im Reiter Einstellungen pflegst du das gemeinsame Webhook-Passwort und die Webhook-Ziele.

Webhook-Passwort

Das Feld Webhook-Passwort legt das Passwort fest, das bei ausgehenden Webhooks für die Basic-Authentifizierung verwendet wird. Der Shop sendet den Webhook mit einem Authentifizierungs-Header, damit das Zielsystem prüfen kann, ob der Aufruf wirklich aus dem Shop kommt.

Webhookliste

Die Webhookliste zeigt alle eingerichteten Webhook-Ziele. Über Webhook erstellen wird ein neues Ziel angelegt.

• Id: interne Kennung des Webhooks.
• Bezeichnung: Objektbereich des Webhooks, zum Beispiel Bestellung, Kunde, Rechnung oder Produktbestand.
• Grund: Ereignis, bei dem der Webhook ausgelöst wird, zum Beispiel Erstellung, Aktualisierung, Löschung, Statuswechsel oder Bestandsänderung.
• Url: Zieladresse, an die der Webhook gesendet wird.
• Optionen: öffnet die Bearbeitung oder löscht den Webhook nach Bestätigung.

Webhook erstellen oder bearbeiten

Das Formular enthält nur die sichtbaren Einstellungen, die für die Ausführung relevant sind.

• Aktiv: steuert, ob der Webhook für sein Ereignis verwendet wird.
• Aktion: wählt beim Erstellen aus, für welchen Objektbereich und welchen Auslöser der Webhook gelten soll. Bei bestehenden Webhooks wird die Aktion nur angezeigt und nicht nachträglich geändert.
• Webhook-URL: Zieladresse des externen Systems. An diese Adresse sendet der Shop den Webhook, sobald das passende Ereignis eintritt.

Reiter Logbuch

Das Logbuch zeigt die erzeugten Webhook-Jobs. Damit lässt sich nachvollziehen, ob ein Ereignis bereits versendet wurde, noch aussteht oder beim Zielsystem fehlgeschlagen ist.

Suche und Filter

Über die Suche können Webhooks nach Event, Ziel-URL, Payload-Inhalt und Status gefunden werden. Zusätzlich stehen im Filterbereich drei Filteroptionen zur Verfügung:

• Datum und Uhrzeit: grenzt das Logbuch über einen Zeitraum ein. Das Feld von filtert ab diesem Zeitpunkt, das Feld bis filtert bis zu diesem Zeitpunkt.
• Event: filtert auf einen konkreten Webhook-Auslöser, zum Beispiel einen bestimmten Objektbereich mit Ereignis.
• Status: filtert nach dem Versandzustand Ausstehend, Wird versendet, Erfolgreich oder Fehlgeschlagen.

Aktive Filter werden im Filterbereich hervorgehoben. Wenn die automatische Filterausführung deaktiviert ist, wird der Filter erst über Aktualisieren angewendet. Bei einer Suche ohne Treffer kann das Backend anbieten, aktive Filter zurückzusetzen.

Tabelle im Logbuch

Die Logbuch-Tabelle ist eine konfigurierbare BsTable. Je nach Bildschirmgröße blendet das Backend einzelne Spalten aus, damit die Ansicht bedienbar bleibt.

• Checkbox: markiert einen oder mehrere Webhook-Jobs für die Stapelverarbeitung.
• Id: interne Kennung des Webhook-Jobs.
• Datum: Zeitpunkt der letzten Aktualisierung des Jobs; standardmäßig wird absteigend sortiert.
• Event: ausgelöstes Webhook-Ereignis.
• Status: aktueller Versandzustand des Jobs.
• HTTP-Code: Rückgabecode des Zielsystems, sofern bereits ein Versandversuch stattgefunden hat.
• Ziel-Url: Adresse, an die der Webhook gesendet wird.
• Versuche: Anzahl der bisherigen Versandversuche.
• Optionen: öffnet Details, setzt den Webhook zum erneuten Versand zurück oder löscht den Job nach Bestätigung.

Statusfarben

Die Zeilenfarbe hilft bei der schnellen Einordnung:

• Erfolgreich: der Webhook wurde erfolgreich versendet.
• Ausstehend: der Webhook wartet auf den nächsten Versandlauf.
• Fehlgeschlagen: der Versand konnte nicht erfolgreich abgeschlossen werden.

Details prüfen

Die Aktion Details öffnet ein Modal mit den wichtigsten technischen Informationen zum einzelnen Job. Dort sind Status, Event, Payload, Header, Antwort des Zielsystems und Fehlermeldung sichtbar. Diese Ansicht hilft besonders, wenn ein Zielsystem den Webhook ablehnt oder unerwartet antwortet.

Webhook erneut versenden

Ein Webhook kann einzeln über die Optionsspalte oder gesammelt über die Stapelverarbeitung erneut versendet werden. Dabei wird der Job wieder auf ausstehend gesetzt, die Anzahl der Versuche zurückgesetzt und der nächste Versandlauf vorbereitet.

Im Formular Erneut versenden kann optional eine Neue Ziel URL angegeben werden. Bleibt das Feld leer, wird die bisherige Zieladresse weiterverwendet.

Webhooks löschen

Einzelne Jobs können über die Optionsspalte gelöscht werden. Mehrere Jobs lassen sich über die Checkbox-Auswahl markieren und über die Stapelverarbeitung mit Löschen entfernen. Das Löschen betrifft nur die Logbuch-Jobs, nicht die Webhook-Ziele im Reiter Einstellungen.

Beispiel: Webhook-Payload in PHP lesen

Wenn ein Zielsystem in PHP umgesetzt wird, kann der eingehende JSON-Body aus dem Request gelesen und als Array weiterverarbeitet werden. Das Beispiel ist bewusst einfach gehalten und dient als Startpunkt für eigene Prüfungen, Logging oder Weiterverarbeitung.

class WebhookHandler
{
    private $postData = array();
    private static $instance;

    private function __construct()
    {
        $rawPayload = file_get_contents('php://input');
        $decodedPayload = json_decode($rawPayload, true);
        $this->postData = $this->cleanInputs(is_array($decodedPayload) ? $decodedPayload : array());
    }

    public static function getInstance()
    {
        if (! isset(self::$instance)) {
            self::$instance = new self();
        }

        return self::$instance;
    }

    public function getPostData()
    {
        return $this->postData;
    }

    private function cleanInputs($data)
    {
        if (is_array($data)) {
            $cleanInput = array();
            foreach ($data as $key => $value) {
                $cleanInput[$key] = $this->cleanInputs($value);
            }
            return $cleanInput;
        }

        return trim(strip_tags((string) $data));
    }
}

$data = WebhookHandler::getInstance()->getPostData();

Typische Prüfung bei Fehlern

1. Im Logbuch nach dem betroffenen Event, Status oder einer passenden Nummer im Payload suchen.
2. Den Zeitraum über Datum und Uhrzeit eingrenzen.
3. Fehlgeschlagene Einträge über den Statusfilter anzeigen.
4. Über Details Antwort, Fehlermeldung und Payload prüfen.
5. Bei Bedarf die Zieladresse korrigieren und den Webhook erneut versenden.