Testen Sie WooCommerce-Webhooks auf Localhost

Um WooCommerce-Webhooks auf localhost zu testen, stellen Sie Ihren lokalen Handler mit einem HTTPS-Tunnel bereit, erstellen Sie einen Webhook unter WooCommerce → Einstellungen → Erweitert → Webhooks und überprüfen Sie ihn X-WC-Webhook-Signature als Base64 HMAC-SHA256-Verdau des Rohkörpers. Lösen Sie eine Bestellung oder Produktänderung in einem sicheren Testgeschäft aus, überprüfen Sie die Lieferung und wiederholen Sie den Vorgang, ohne den Empfänger einzusetzen.

Was WooCommerce sendet und wann

WooCommerce kann eine Liefer-URL benachrichtigen, wenn Bestellungen, Produkte, Gutscheine oder Kunden erstellt, aktualisiert oder gelöscht werden. Durch Erweiterungen können Themen hinzugefügt werden und Entwickler können benutzerdefinierte Themen definieren. Jeder konfigurierte Webhook verfügt über einen Namen, einen Status, ein Thema, eine Bereitstellungs-URL, ein Geheimnis und eine API-Version. Der offizielle WooCommerce-Webhook-Dokumentation beschreibt die Erstellung, Themen, Lieferprotokolle und das Fehlerverhalten.

Ein Webhook wird an ein Thema angehängt, nicht automatisch an jede Store-Mutation. Wählen Sie das engste Thema aus, das Ihre Integration benötigt. Ein Verbraucher, der eine Bestellung erstellt hat, sollte nicht auch jedes Produktupdate verarbeiten. Dies reduziert die Gefährdung personenbezogener Daten, den Datenverkehr und versehentliche Nebenwirkungen bei lokalen Tests.

Erstellen Sie einen Raw-Body-Express-Endpunkt

Die Signatur von WooCommerce wird über den gesendeten Text berechnet. Behalten Sie diese Bytes bei, bis die Überprüfung abgeschlossen ist. Der Signaturheader enthält den Base64-codierten binären HMAC-SHA256-Digest, keine hexadezimale Zeichenfolge.

import express from 'express';
import crypto from 'node:crypto';

const app = express();

function validWooSignature(rawBody, supplied, secret) {
  if (!supplied || !secret) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('base64');
  const a = Buffer.from(supplied);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  '/webhooks/woocommerce',
  express.raw({ type: 'application/json', limit: '2mb' }),
  async (req, res) => {
    const supplied = req.get('x-wc-webhook-signature');
    if (!validWooSignature(req.body, supplied, process.env.WC_WEBHOOK_SECRET)) {
      return res.sendStatus(401);
    }

    const payload = JSON.parse(req.body.toString('utf8'));
    await webhookInbox.insertOnce({
      deliveryId: req.get('x-wc-webhook-delivery-id'),
      topic: req.get('x-wc-webhook-topic'),
      payload,
    });
    return res.sendStatus(202);
  },
);

app.use(express.json());
app.listen(3000);

Der routenspezifische Rohparser muss vor einem globalen JSON-Parser ausgeführt werden. Wenn die Middleware zuerst den Text analysiert, kann die erneute Stringifizierung des Objekts dazu führen, dass Leerzeichen oder Escapezeichen geändert werden und der Digest ungültig wird. Dies ist die gleiche Rohkörperregel, die im behandelt wird Leitfaden zur Webhook-Signatur, aber WooCommerce verwendet speziell die Base64-Ausgabe.

Starten Sie den HTTPS-Tunnel

1. Starten Sie Ihren Receiver und vergewissern Sie sich, dass er mithört http://localhost:3000.
2. Laufen npx portpreview 3000 in einem zweiten Terminal.
3. Kopieren Sie die öffentliche HTTPS-URL und hängen Sie sie an /webhooks/woocommerce.
4. Lassen Sie den Prozess laufen, während WordPress seine ersten Ping- und Themenzustellungen sendet.

Der WordPress-Host – nicht der Browser, in dem Sie wp-admin geöffnet haben – muss in der Lage sein, die öffentliche URL zu erreichen. Ein Tunnel verbindet diese öffentliche Anfrage mit Ihrem privaten Entwicklungsprozess. Es bietet außerdem vertrauenswürdiges TLS, sodass Sie keinen Router-Port freigeben oder Ihr eigenes öffentliches Zertifikat installieren müssen.

Konfigurieren Sie den Webhook in WooCommerce

1. Offen WooCommerce → Einstellungen → Erweitert → Webhooks.
2. Wählen Webhook hinzufügen und geben Sie ihm einen erkennbaren lokalen Entwicklungsnamen.
3. Wählen Aktiv Status und ein bestimmtes Thema, z. B. Bestellung erstellt.
4. Fügen Sie die vollständige Tunnelbereitstellungs-URL ein.
5. Generieren Sie ein langes Zufallsgeheimnis und geben Sie den gleichen Wert ein WC_WEBHOOK_SECRET.
6. Speichern Sie den Webhook und lösen Sie dann das Thema in einem Testspeicher aus.

Wenn ein aktiver Webhook zum ersten Mal gespeichert wird, sendet WooCommerce einen Ping an die Liefer-URL. Der Ping bestätigt die Konnektivität, ist jedoch kein Ersatz für eine echte Auftragsnutzlast. Sorgen Sie dafür, dass Ihr Endpunkt die anfängliche Anfrage toleriert, und erstellen oder aktualisieren Sie dann Testdaten, um das ausgewählte Thema auszuüben.

export WC_WEBHOOK_SECRET="$(openssl rand -base64 48)"

Wenn Sie ein Base64-Geheimnis in eine Umgebungsdatei einfügen, zitieren Sie es, damit die Zeichensetzung erhalten bleibt. Das Geheimnis ist der HMAC-Schlüssel; WooCommerce-REST-API-Konsumentenschlüssel und WordPress-Passwörter sind unabhängige Anmeldeinformationen.

Verwenden Sie Kopfzeilen, um Lieferungen weiterzuleiten und zu verfolgen

WooCommerce enthält nützliche Metadaten-Header. Dazu gehören je nach Version und Umgebung das Thema, die Ressource, das Ereignis, die Quelle, die Webhook-ID und die Liefer-ID. Behandeln Sie Namen ohne Berücksichtigung der Groß- und Kleinschreibung, wie es HTTP erfordert. Verwenden Sie den Betreff für den Versand und die Liefer-ID zur Rückverfolgbarkeit, aber authentifizieren Sie immer zuerst den Körper.

const handlers = {
  'order.created': handleOrderCreated,
  'order.updated': handleOrderUpdated,
  'product.updated': handleProductUpdated,
};

const handler = handlers[topic];
if (handler) await handler(payload);
else await recordUnsupportedTopic(topic);

Leiten Sie das Thema nicht nur aus der JSON-Form ab. Eine erstellte Bestellung und eine auftragsaktualisierte Nutzlast können ähnlich aussehen, während die richtige nachgelagerte Aktion unterschiedlich ist. Umgekehrt lehnen Sie eine Kombination aus Header und Thema ab, für deren Annahme Ihr Endpunkt nie konfiguriert wurde.

Auftragsnutzlasten defensiv verarbeiten

Verwenden Sie unveränderliche Bezeichner

Korrelieren Sie Datensätze nach Shop-Identität und WooCommerce-Objekt-ID, nicht nach Bestellnummernformatierung, Kunden-E-Mail oder Anzeigenamen. Zwei Filialen können beide die Bestell-ID 42 haben, daher benötigen Integrationen mit mehreren Filialen einen zusammengesetzten Schlüssel.

Erwarten Sie, dass Erweiterungen Felder ändern

Zahlungs-, Abonnement-, Steuer-, Checkout- und Erfüllungserweiterungen können Metadaten und Einzelpostenfelder hinzufügen. Validieren Sie die Felder, die Ihre Geschäftslogik benötigt, ignorieren Sie unbekannte Felder und speichern Sie eine Schemaversion oder eine minimale redigierte Fixture für Regressionstests.

Trennen Sie den Ereigniseingang von der Erfüllung

Ein Webhook mit der Meldung, dass eine Bestellung geändert wurde, sollte in eine dauerhafte Warteschlange oder einen Posteingang gelangen. Nach der Bestätigung sollten Bestandssynchronisierung, Versandetiketten, ERP-Anrufe und Kunden-E-Mails ausgeführt werden. Dies verhindert, dass eine langsame Abhängigkeit dazu führt, dass WooCommerce einen erfolgreichen Empfang als fehlgeschlagene Lieferung interpretiert.

Modellaktualisierungen als Zustandsübergänge

Eine Bestellung kann sich in den Status „Ausstehend“, „Verarbeitung“, „Zurückgestellt“, „Abgeschlossen“, „Storniert“, „Erstattet“ oder „Fehlgeschlagen“ bewegen. Aktualisierungen können schnell erfolgen und die Lieferreihenfolge ist kein sicherer Ersatz für den Vergleich von Zeitstempeln und dem aktuellen Quellstatus. Machen Sie wiederholte Übergänge unschädlich.

Idempotenz ist für Handelsveranstaltungen zwingend erforderlich

Nach dem Commit Ihres Empfängers, aber bevor WooCommerce die Antwort sieht, kann es zu einer Zeitüberschreitung kommen. Eine erneute Zustellung führt dann zur gleichen Geschäftsaktion, es sei denn, der Handler ist idempotent. Bewahren Sie die Liefer-ID auf, sofern vorhanden. Erzwingen Sie außerdem die Einzigartigkeit auf Domänenebene, z. B. eine Erfüllungsanfrage pro Geschäft und Bestellübergang.

await db.transaction(async (tx) => {
  if (!(await tx.deliveries.claim(deliveryId))) return;
  await tx.orders.applyWooCommerceEvent(storeId, topic, payload);
  await tx.outbox.enqueueRequiredActions(storeId, topic, payload.id);
});

Eine Posteingangs- und Postausgangstransaktion verhindert sowohl doppelte Bearbeitung als auch verlorene Folgearbeiten. Sehen Webhook-Wiederholung und Idempotenz für das vollständige Muster.

Verwenden Sie WooCommerce-Protokolle, um die Absenderseite zu debuggen

WooCommerce zeichnet Webhook-Lieferungen auf. Offen WooCommerce → Status → Protokolle und filtern Sie nach der in der offiziellen Dokumentation beschriebenen Webhook-Lieferquelle. Vergleichen Sie die Zustellungs-URL, die Anforderungszeit, den Antwortstatus und den Antworttext mit Ihrem lokalen Tunnel-Trace. Absenderprotokolle beantworten, ob WordPress versucht hat, die Anfrage zu stellen. Empfängerprotokolle beantworten, was Ihre Anwendung damit gemacht hat.

Kopieren Sie keine ungeschwärzten Auftragsdaten in eine öffentliche Ausgabe. Es kann Namen, Rechnungs- und Lieferadressen, E-Mail, Telefonnummer, Produktauswahl und Zahlungsmetadaten enthalten. Reduzieren Sie das Fixture auf die Felder, die zur Reproduktion des Fehlers erforderlich sind.

Beheben Sie häufige WooCommerce-Webhook-Fehler

Der Webhook wird deaktiviert

WooCommerce deaktiviert einen Webhook automatisch nach mehr als fünf aufeinanderfolgenden Zustellungsfehlern. Antworten außerhalb von 2xx, 301 oder 302 gelten gemäß dem offiziellen Leitfaden als Fehler. Reparieren Sie den Endpunkt, aktivieren Sie den Webhook erneut und senden Sie einen kontrollierten Test. Vermeiden Sie auf jeden Fall Weiterleitungen: Sie erschweren das Signatur-Debugging und können signierte Kundendaten versehentlich an einen unbeabsichtigten Host senden.

Die Signatur ist immer unterschiedlich

Hashen Sie den genauen Rohkörper mit dem konfigurierten Geheimnis des Webhooks, fordern Sie die binäre HMAC-Ausgabe an und kodieren Sie ihn dann mit Base64. Das heißt, in Node .digest('base64'). Häufige Fehler sind die Verwendung von Hex, die Verwendung eines REST-API-Geheimnisses, das Parsen von JSON zuerst oder das Einfügen zusätzlicher Newline-Bytes.

Der anfängliche Ping funktioniert, Bestellereignisse jedoch nicht

Bestätigen Sie, dass das ausgewählte Thema mit der von Ihnen ausgelösten Aktion übereinstimmt. Das Erstellen einer Bestellung und das Ändern einer bestehenden Bestellung sind unterschiedliche Themen. Stellen Sie sicher, dass der Status „Aktiv“ ist, überprüfen Sie die WooCommerce-Protokolle und stellen Sie sicher, dass kein Plugin oder Staging-Cache den zugrunde liegenden Hook verhindert.

Lokale Anfragen geben 404 zurück

Überprüfen Sie den vollständigen Pfad, die Routenmethode und den Tunnelzielport. WordPress muss posten /webhooks/woocommerce, nicht nur der Tunnelursprung. Die Framework-Middleware sollte den Webhook nicht auf eine lokalisierte oder authentifizierte Seite umleiten.

Es kommt zu Zeitüberschreitungen bei den Lieferungen

Behalten Sie das authentifizierte Ereignis bei und geben Sie umgehend 200 oder 202 zurück. Verschieben Sie Remote-API-Aufrufe und umfangreiche Transformationen auf einen Worker. Überprüfen Sie, ob lokale Haltepunkte die Anforderung lange genug anhalten, um als Fehler eingestuft zu werden.

Das erneute Abspielen einer Nutzlast führt zu einem 401

Eine erfasste Anfrage muss die exakten Rohbytes und den Signaturheader enthalten. Durch das Bearbeiten von JSON wird die ursprüngliche Signatur ungültig. Verwenden Sie für Geschäftslogiktests eine bereinigte Vorrichtung nach der Verifizierungsgrenze. Generieren Sie für End-to-End-Tests einen neuen HMAC mit einem dedizierten Testgeheimnis. Folgen Sie dem Sicherer Wiedergabe-Workflow.

Sicherheitscheckliste für lokale Speicherdaten

• Testen Sie nach Möglichkeit in einem Staging-Shop mit synthetischen Kunden und Produkten.
• Verwenden Sie ein einzigartiges Webhook-Geheimnis für die lokale Entwicklung und rotieren Sie es nach der Offenlegung.
• Überprüfen Sie die Signatur, bevor Sie den Text analysieren, protokollieren oder in die Warteschlange stellen.
• Erwartete Speicherquelle und Thema werden nach der kryptografischen Überprüfung auf die Zulassungsliste gesetzt.
• Schwärzen Sie Adressen, Kontaktdaten, Bestellnotizen und Zahlungsmetadaten aus Erfassungen.
• Deaktivieren Sie niemals die TLS-Überprüfung und geben Sie dem Empfänger niemals wp-admin-Anmeldeinformationen preis.

Die lokale Architektur sollte zur Produktion passen: HTTPS-Transport, Raw-Body-Authentifizierung, dauerhafte Akzeptanz, idempotente Verarbeitung, schnelle Reaktion und überprüfbare Fehler. Vergleichen Sie für einen anderen Commerce-Anbieter mit einem anderen HMAC-Header die Leitfaden für den lokalen Webhook von Shopify.