Zum Inhalt

WooCommerce Webhook Einrichtung

Diese Anleitung zeigt, wie Sie den WooCommerce-Webhook für HostAdmin einrichten. Der Webhook ermöglicht es WooCommerce, HostAdmin automatisch über abgeschlossene Bestellungen zu informieren.

Übersicht

Webhook-Endpunkt: /api/woocommerce/webhook

Verarbeitetes Event: Topic order.updated, nur wenn status == completed. Alle anderen Topics/Status werden ignoriert.

Asynchrone Zustellung über WP-Cron

WooCommerce liefert Webhooks nicht sofort bei der Statusänderung aus, sondern über den Action Scheduler (Hook woocommerce_deliver_webhook_async) als geplante Hintergrundaufgabe. Läuft WP-Cron auf der WooCommerce-Installation nicht zuverlässig (z. B. weil die Seite selten besucht wird und wp-cron.php nur bei Seitenaufrufen getriggert wird), stauen sich die Zustellungen und kommen erst verzögert — teils erst nach mehreren Minuten oder gar nicht, bis WP-Cron wieder läuft — bei HostAdmin an. Für produktive Installationen empfiehlt sich ein echter System-Cronjob (z. B. alle 1–5 Minuten wp cron event run --due-now) statt des Standard-Pseudo-Cron. Zum Prüfen des Zustellstatus: WooCommerce → Status → Geplante Aktionen zeigt alle geplanten/ausgeführten/fehlgeschlagenen Webhook-Zustellversuche mit Zeitstempel.

Schritt 1: Webhook in WooCommerce anlegen

  1. WordPress-Adminbereich öffnen → WooCommerce → Einstellungen → Erweitert → Webhooks
  2. "Webhook hinzufügen" klicken
  3. Felder ausfüllen:
  4. Name: z. B. "HostAdmin Bestellungen"
  5. Status: Aktiv
  6. Thema: Bestellung aktualisiert (order.updated)
  7. Zustellungs-URL: 
    https://ihre-domain.de/api/woocommerce/webhook
  8. Secret: Ein zufälliges, sicheres Secret generieren (z. B. openssl rand -hex 32) und notieren
  9. API-Version: WP REST API Integration v3 (aktuellste verfügbare Version)
  10. Speichern

Secret geheim halten

Das Webhook-Secret ist wie ein Passwort. Teilen Sie es niemals öffentlich und committen Sie es nicht in Git.

Kein festes Format

Anders als Stripe (whsec_...) gibt WooCommerce für das Secret kein Format oder Präfix vor — es ist ein beliebiger String, der 1:1 als HMAC-SHA256-Schlüssel für die Signaturberechnung verwendet wird. openssl rand -hex 32 ist lediglich eine Empfehlung für einen ausreichend langen, zufälligen Wert, keine WooCommerce-Vorgabe. Wichtig ist nur, dass exakt derselbe String sowohl im WooCommerce-Webhook-Feld "Secret" als auch in WOOCOMMERCE_WEBHOOK_SECRET (.env) hinterlegt wird.

Schritt 2: Webhook in HostAdmin konfigurieren

.env im src/-Verzeichnis öffnen oder Docker Env ergänzen:

WOOCOMMERCE_WEBHOOK_SECRET=<das in Schritt 1 generierte Secret>
WOOCOMMERCE_WEBHOOK_ENABLED=true

Standardwert für WOOCOMMERCE_WEBHOOK_ENABLED

Fehlt die Variable, gilt true. Setzen Sie sie explizit auf false, um den Endpunkt gezielt zu deaktivieren (z. B. während Wartungsarbeiten) — der Endpunkt antwortet dann auf jeden Request mit 403 Forbidden, unabhängig von der Signatur.

Docker-Installation: Änderungen werden nach docker exec hostadmin-app php artisan config:clear und docker-compose restart app übernommen.

Schritt 3: Artikelnummern abgleichen

Der Webhook matcht die WooCommerce-SKU jedes Bestellpositions gegen die Artikelnummer (article_number) einer ServiceDefinition in HostAdmin. Stellen Sie sicher, dass:

  • jedes WooCommerce-Produkt eine SKU gesetzt hat,
  • diese SKU exakt der article_number der entsprechenden ServiceDefinition in HostAdmin entspricht (Admin → Service-Definitionen).

Passt eine SKU zu keiner ServiceDefinition, wird die Position übersprungen und als Fehler geloggt — die Bestellung wird trotzdem für die übrigen, gematchten Positionen angelegt.

Schritt 4: Webhook testen

Eine Testbestellung in einer WooCommerce-Testinstallation durchführen und auf Status "Abgeschlossen" setzen. Anschließend Logs prüfen:

docker exec hostadmin-app tail -f storage/logs/laravel.log | grep -i woocommerce

Erwartete Log-Einträge bei Erfolg:

[...] local.INFO: WooCommerce webhook received {"topic":"order.updated","order_id":123,"status":"completed"}
[...] local.INFO: WooCommerce order processed {"order_id":123,"customer_id":45,"services_created":1}

Die Bestellung sollte danach im Admin-Panel unter Bestellungen (/admin/bestellungen) auftauchen.

Troubleshooting

Webhook wird mit 403 abgelehnt

Ursache: WOOCOMMERCE_WEBHOOK_ENABLED=false gesetzt.

Lösung: Variable entfernen oder auf true setzen, dann config:clear + Container-Neustart.

Webhook wird mit 400 abgelehnt ("Invalid signature")

Mögliche Ursachen:

  1. WOOCOMMERCE_WEBHOOK_SECRET fehlt oder stimmt nicht mit dem in WooCommerce hinterlegten Secret überein.
  2. Ein Reverse Proxy (nginx, Cloudflare) verändert den Request-Body, bevor er HostAdmin erreicht — die Signaturprüfung benötigt den unveränderten Raw-Body.

Lösung: 

docker exec hostadmin-app grep WOOCOMMERCE_WEBHOOK_SECRET .env
docker exec hostadmin-app php artisan config:clear
docker-compose restart app

Bestellung wird empfangen, aber keine CustomerService angelegt

Ursache: Keine SKU im Bestellposten gesetzt, oder keine ServiceDefinition mit passender article_number gefunden.

Lösung: Logs prüfen (grep -i "SKU" storage/logs/laravel.log), Artikelnummern in WooCommerce und HostAdmin abgleichen.

Bestellung kommt gar nicht an (oder deutlich verzögert)

Zuerst prüfen: WooCommerce → Status → Geplante Aktionen — läuft dort noch eine Zustellung als "Ausstehend"? Dann liegt es an WP-Cron (siehe Hinweis "Asynchrone Zustellung" oben), nicht an HostAdmin. Ein Seitenaufruf auf der WordPress-Seite triggert den Pseudo-Cron und liefert die gestauten Zustellungen nach.

Erst wenn dort kein ausstehender Eintrag mehr existiert und trotzdem nichts bei HostAdmin ankommt: WooCommerce wiederholt fehlgeschlagene Zustellungen nicht automatisch (anders als Stripe). Bei Ausfällen (Endpunkt nicht erreichbar, 5xx-Fehler) muss die Bestellung manuell in HostAdmin nacherfasst werden. Zustellstatus lässt sich in WooCommerce unter WooCommerce → Einstellungen → Erweitert → Webhooks → Ihr Webhook → Zustellungsprotokoll einsehen.

Checkliste

WooCommerce

  • Webhook angelegt, Thema order.updated, Status Aktiv
  • Zustellungs-URL korrekt (HTTPS für Produktion)
  • Secret generiert und notiert
  • Zuverlässiges WP-Cron eingerichtet (System-Cronjob empfohlen, siehe Hinweis oben), sonst verzögerte Zustellung

HostAdmin

  • WOOCOMMERCE_WEBHOOK_SECRET in .env gesetzt (identisch zum WooCommerce-Secret)
  • WOOCOMMERCE_WEBHOOK_ENABLED=true gesetzt (oder Variable weggelassen)
  • Artikelnummern zwischen WooCommerce-SKUs und ServiceDefinitions abgeglichen
  • Middleware-Ausnahmen in bootstrap/app.php vorhanden (api/woocommerce/webhook bei CSRF/TrimStrings/ConvertEmptyStrings)

Testing

  • Testbestellung durchgeführt und auf "Abgeschlossen" gesetzt
  • Log-Eintrag "WooCommerce order processed" vorhanden
  • Bestellung erscheint unter /admin/bestellungen
  • Admin-Benachrichtigungs-E-Mail erhalten (falls notify_email_active aktiviert)

Siehe auch: WooCommerce Webhook API-Referenz