Search by

ospo / module-webhooks

splendidinternet

Meldet Ereignisse aus Mage-OS als signierte Webhooks (Firma oder Kundenkonto wartet auf Freigabe, niedriger Lagerbestand), mit Zustellliste und Wiederholung

Package info

codeberg.org/OSPO/magento2-module-webhooks

Issues

Type:magento2-module

pkg:composer/ospo/module-webhooks

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

1.0.0 2026-11-17 14:50 UTC

This package is auto-updated.

Last update: 2026-11-17 18:55:13 UTC


README

Meldet Ereignisse aus dem Shop als Webhook an eine frei wählbare Adresse, zum Beispiel an einen Flow in Activepieces, n8n oder an ein eigenes System.

Entstanden im OSPO-Projekt. Mage-OS verschickt von sich aus keine Webhooks, und das regelmäßige Abfragen der REST-Schnittstelle skaliert bei großen Katalogen und vielen Kundenkonten schlecht.

Ereignisse

EreignisWannVoraussetzung
company.awaiting_approvalEine Firma registriert sich und wartet auf die Freigabe.Firmenmodul von Orangecat
customer.awaiting_approvalEin Kunde registriert sich im Shop, und sein Konto muss erst freigegeben werden.Firmenmodul von Orangecat
inventory.low_stockDie verkäufliche Menge von Artikeln ist unter die Meldegrenze gefallen.keine

Bei einer Firmenregistrierung geht nur company.awaiting_approval raus, das dabei angelegte Konto des Firmen-Admins wird nicht zusätzlich gemeldet.

Ohne das Firmenmodul von Orangecat bleiben die beiden Freigabe-Ereignisse einfach stumm, das Modul lässt sich trotzdem installieren.

Lagerbestand: Alle 15 Minuten prüft ein Cron-Job je Lager die verkäufliche Menge (Summe aller aktiven Quellen des Lagers plus offene Reservierungen) gegen die Meldegrenze. Die Meldegrenze ist die Einstellung „Benachrichtigen bei Menge unter“ der Lagerverwaltung, je Artikel und Quelle oder der Standardwert aus cataloginventory/item_options/notify_stock_qty. Geprüft werden aktive Artikel mit Lagerverwaltung. Konfigurierbare Artikel, Bündel und Gruppenartikel bleiben außen vor, weil sie keinen eigenen Bestand führen, gemeldet werden ihre Varianten und Bestandteile. Ein Artikel wird einmal gemeldet und erst wieder, nachdem er zwischendurch aufgefüllt war. Eine Meldung enthält bis zu 100 Artikel, bei mehr Artikeln gehen mehrere Meldungen raus. Der erste Lauf nach dem Einschalten meldet alle Artikel, die in dem Moment unter der Grenze liegen.

Aufbau einer Meldung

HTTP-POST mit JSON-Inhalt:

{
    "id": "0c8a6f0e-4d0b-4a53-9a55-0d6b4f6f1c11",
    "event": "company.awaiting_approval",
    "created_at": "2026-11-17T14:05:00+00:00",
    "website": {"id": 1, "code": "base", "name": "Main Website", "url": "https://shop.example.org/"},
    "data": {
        "company_id": 12,
        "name": "Beispiel Handwerk GmbH",
        "name_legal": "Beispiel Handwerk GmbH",
        "email": "firma@example.org",
        "tax_id": "DE000000000",
        "address": "Teststraße 5",
        "postalcode": "24103",
        "city": "Kiel",
        "country": "DE",
        "telephone": "04310000001"
    }
}

data je Ereignis:

  • company.awaiting_approval: company_id, name, name_legal, email, tax_id, address, postalcode, city, country, telephone
  • customer.awaiting_approval: customer_id, email, firstname, lastname, group_id, taxvat
  • inventory.low_stock: stock_id, products (Liste mit sku, name, salable_qty, threshold)

Kopfzeilen:

KopfzeileInhalt
X-Ospo-EventName des Ereignisses
X-Ospo-DeliveryKennung der Meldung, gleich dem Feld id. Bleibt bei Wiederholungen gleich.
X-Ospo-TimestampUnix-Zeit des Zustellversuchs
X-Ospo-Signaturesha256= gefolgt vom HMAC SHA-256 über <Timestamp>.<Inhalt> mit dem Schlüssel aus der Konfiguration. Fehlt, wenn kein Schlüssel hinterlegt ist.

Signatur prüfen (Beispiel in PHP):

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
$valid = hash_equals($expected, $signature) && abs(time() - (int)$timestamp) < 300;

Zustellung

Das Ereignis wird nur in die Tabelle ospo_webhooks_delivery geschrieben, der Shop wartet nicht auf den Empfänger. Ein Cron-Job stellt jede Minute zu. Als zugestellt gilt eine Meldung bei einer Antwort mit Status 2xx. Sonst wird sie nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde, 3, 6, 12 und 24 Stunden erneut versucht und danach als failed markiert. Der Empfänger sollte doppelte Meldungen an id erkennen.

Zugestellte Meldungen werden nach 30 Tagen gelöscht, endgültig gescheiterte nach 90 Tagen. Stand und letzter Fehler stehen in der Tabelle (status, attempts, last_http_status, last_error).

Der Magento-Cron muss laufen.

Konfiguration

Im Backend unter Shops -> Konfiguration -> OSPO -> Webhooks (Standard oder je Website) oder per bin/magento config:set:

PfadStandardBedeutung
ospo_webhooks/general/enabled0Webhooks senden
ospo_webhooks/general/secretleerSchlüssel zum Signieren (verschlüsselt gespeichert)
ospo_webhooks/company_awaiting_approval/enabled0Ereignis senden
ospo_webhooks/company_awaiting_approval/urlleerZiel-Adresse
ospo_webhooks/customer_awaiting_approval/enabled0Ereignis senden
ospo_webhooks/customer_awaiting_approval/urlleerZiel-Adresse
ospo_webhooks/low_stock/enabled0Ereignis senden
ospo_webhooks/low_stock/urlleerZiel-Adresse

Teilen sich mehrere Websites ein Lager und dieselbe Ziel-Adresse, geht die Bestandsmeldung nur einmal raus.

Die Meldungen zu Firmen und Kundenkonten enthalten personenbezogene Daten. Die Ziel-Adresse sollte deshalb per HTTPS erreichbar sein und zu einem System gehören, das diese Daten verarbeiten darf.

Testen

bin/magento ospo:webhooks:test inventory.low_stock --website=base

Der Befehl schickt sofort eine Beispielmeldung (mit "test": true) an die hinterlegte Adresse und gibt den HTTP-Status aus.

Installation

composer require ospo/module-webhooks
bin/magento module:enable Ospo_Webhooks
bin/magento setup:upgrade

Im Production-Modus danach bin/magento setup:di:compile (bzw. deploy:mode:set production).

Lizenz: OSL-3.0, wie Magento Open Source und Mage-OS.