ospo / module-webhooks
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
Type:magento2-module
pkg:composer/ospo/module-webhooks
Requires
- php: ~8.3.0||~8.4.0
- magento/framework: *
- magento/module-catalog: *
- magento/module-catalog-inventory: *
- magento/module-config: *
- magento/module-cron: *
- magento/module-customer: *
- magento/module-eav: *
- magento/module-inventory: *
- magento/module-inventory-low-quantity-notification: *
- magento/module-inventory-reservations: *
- magento/module-inventory-sales: *
- magento/module-store: *
Requires (Dev)
None
Suggests
- orangecat/module-company: Needed for the events company.awaiting_approval and customer.awaiting_approval
Provides
None
Conflicts
None
Replaces
None
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
| Ereignis | Wann | Voraussetzung |
|---|---|---|
company.awaiting_approval | Eine Firma registriert sich und wartet auf die Freigabe. | Firmenmodul von Orangecat |
customer.awaiting_approval | Ein Kunde registriert sich im Shop, und sein Konto muss erst freigegeben werden. | Firmenmodul von Orangecat |
inventory.low_stock | Die 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,telephonecustomer.awaiting_approval:customer_id,email,firstname,lastname,group_id,taxvatinventory.low_stock:stock_id,products(Liste mitsku,name,salable_qty,threshold)
Kopfzeilen:
| Kopfzeile | Inhalt |
|---|---|
X-Ospo-Event | Name des Ereignisses |
X-Ospo-Delivery | Kennung der Meldung, gleich dem Feld id. Bleibt bei Wiederholungen gleich. |
X-Ospo-Timestamp | Unix-Zeit des Zustellversuchs |
X-Ospo-Signature | sha256= 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:
| Pfad | Standard | Bedeutung |
|---|---|---|
ospo_webhooks/general/enabled | 0 | Webhooks senden |
ospo_webhooks/general/secret | leer | Schlüssel zum Signieren (verschlüsselt gespeichert) |
ospo_webhooks/company_awaiting_approval/enabled | 0 | Ereignis senden |
ospo_webhooks/company_awaiting_approval/url | leer | Ziel-Adresse |
ospo_webhooks/customer_awaiting_approval/enabled | 0 | Ereignis senden |
ospo_webhooks/customer_awaiting_approval/url | leer | Ziel-Adresse |
ospo_webhooks/low_stock/enabled | 0 | Ereignis senden |
ospo_webhooks/low_stock/url | leer | Ziel-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.