Przetestuj webhooki WooCommerce na Localhost

Aby przetestować webhooki WooCommerce na hoście lokalnym, udostępnij lokalny moduł obsługi za pomocą tunelu HTTPS, utwórz webhook w WooCommerce → Ustawienia → Zaawansowane → Webhooks i zweryfikuj X-WC-Webhook-Signature jako wyciąg Base64 HMAC-SHA256 surowego ciała. Złóż zamówienie lub zmień produkt w bezpiecznym sklepie testowym, sprawdź dostawę i wykonaj iterację bez konieczności wdrażania odbiornika.

Co i kiedy wysyła WooCommerce

WooCommerce może powiadamiać adres URL dostawy, gdy zamówienia, produkty, kupony lub klienci są tworzone, aktualizowane lub usuwane. Rozszerzenia mogą dodawać tematy, a programiści mogą definiować tematy niestandardowe. Każdy skonfigurowany webhook ma nazwę, status, temat, adres URL dostarczania, klucz tajny i wersję API. oficjalna dokumentacja webhooka WooCommerce opisuje tworzenie, tematy, dzienniki dostaw i zachowanie w przypadku awarii.

Webhook jest dołączany automatycznie do tematu, a nie do każdej mutacji sklepu. Wybierz najwęższy temat, jakiego potrzebuje Twoja integracja. Konsument utworzony na zamówienie nie powinien również przetwarzać każdej aktualizacji produktu. Zmniejsza to ryzyko narażenia danych osobowych, ruchu i przypadkowych skutków ubocznych podczas testów lokalnych.

Utwórz punkt końcowy Express w postaci surowej

Podpis WooCommerce jest obliczany na podstawie wysyłanej treści. Zachowaj te bajty do czasu zakończenia weryfikacji. Nagłówek podpisu zawiera binarny skrót HMAC-SHA256 zakodowany w formacie Base64, a nie ciąg szesnastkowy.

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);

Surowy analizator składni specyficzny dla trasy musi działać przed globalnym analizatorem składni JSON. Jeśli oprogramowanie pośredniczące najpierw analizuje treść, ponowne utworzenie łańcucha obiektu może zmienić białe znaki lub ucieczkę i unieważnić skrót. Jest to ta sama zasada dotycząca surowego ciała, opisana w artykule przewodnik po podpisach webhooków, ale WooCommerce specjalnie używa danych wyjściowych Base64.

Uruchom tunel HTTPS

1. Uruchom odbiornik i potwierdź, że słucha http://localhost:3000.
2. Uruchomić npx portpreview 3000 w drugim terminalu.
3. Skopiuj publiczny adres URL HTTPS i dołącz /webhooks/woocommerce.
4. Kontynuuj proces, podczas gdy WordPress wysyła początkowe polecenia ping i tematy.

Host WordPress — a nie przeglądarka, w której otworzyłeś wp-admin — musi mieć dostęp do publicznego adresu URL. Tunel łączy publiczne żądania z prywatnym procesem rozwoju. Zapewnia również zaufany TLS, więc nie musisz ujawniać portu routera ani instalować własnego certyfikatu publicznego.

Skonfiguruj webhook w WooCommerce

1. Otwarte WooCommerce → Ustawienia → Zaawansowane → Webhooki.
2. Wybierać Dodaj webhooka i nadać mu rozpoznawalną nazwę o charakterze lokalnym i rozwojowym.
3. Wybierać Aktywny status i konkretny temat, np. Zamówienie utworzone.
4. Wklej pełny adres URL dostarczania przez tunel.
5. Wygeneruj długi losowy sekret i umieść w nim identyczną wartość WC_WEBHOOK_SECRET.
6. Zapisz webhook, a następnie uruchom temat w sklepie testowym.

Gdy aktywny webhook zostanie zapisany po raz pierwszy, WooCommerce wysyła sygnał ping na adres URL dostawy. Ping potwierdza łączność, ale nie zastępuje ładunku prawdziwego zamówienia. Spraw, aby Twój punkt końcowy tolerował początkowe żądanie, a następnie utwórz lub zaktualizuj dane testowe, aby wykonać wybrany temat.

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

Jeśli wkleisz sekret Base64 do pliku środowiska, zacytuj go, aby zachować interpunkcję. Sekretem jest klucz HMAC; Klucze konsumenckie WooCommerce REST API i hasła WordPress to niepowiązane dane uwierzytelniające.

Używaj nagłówków do wyznaczania trasy i śledzenia dostaw

WooCommerce zawiera przydatne nagłówki metadanych. W zależności od wersji i środowiska są to temat, zasób, zdarzenie, źródło, identyfikator elementu webhook i identyfikator dostarczenia. Traktuj nazwy bez uwzględniania wielkości liter, zgodnie z wymaganiami protokołu HTTP. Użyj tematu wysyłki i identyfikatora dostawy w celu śledzenia, ale zawsze najpierw uwierzytelniaj ciało.

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

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

Nie wnioskuj tematu wyłącznie z kształtu JSON. Utworzone zamówienie i zaktualizowany ładunek zamówienia mogą wyglądać podobnie, natomiast prawidłowe dalsze działania mogą się różnić. I odwrotnie, odrzuć kombinację nagłówka/tematu, do której Twój punkt końcowy nigdy nie był skonfigurowany.

Przetwarzaj ładunki w sposób defensywny

Użyj niezmiennych identyfikatorów

Koreluj rekordy według tożsamości sklepu i identyfikatora obiektu WooCommerce, a nie formatu numeru zamówienia, adresu e-mail klienta lub nazw wyświetlanych. Obydwa sklepy mogą mieć identyfikator zamówienia 42, dlatego integracje wielu sklepów wymagają klucza złożonego.

Spodziewaj się, że rozszerzenia zmienią pola

Rozszerzenia dotyczące płatności, subskrypcji, podatków, realizacji transakcji i realizacji umożliwiają dodanie pól metadanych i elementów zamówienia. Sprawdź poprawność pól wymaganych przez logikę biznesową, zignoruj ​​nieznane pola i zapisz wersję schematu lub minimalne zredagowane urządzenie do testów regresyjnych.

Oddziel potwierdzenie zdarzenia od realizacji

Webhook informujący o zmianie zamówienia powinien trafić do trwałej kolejki lub skrzynki odbiorczej. Synchronizacja zapasów, etykiety wysyłkowe, połączenia ERP i wiadomości e-mail do klientów powinny zostać uruchomione po potwierdzeniu. Zapobiega to sytuacji, w której powolna zależność powoduje, że WooCommerce interpretuje pomyślny paragon jako nieudaną dostawę.

Aktualizacje modelu w miarę zmian stanu

Zamówienie może przechodzić przez stany oczekujące, przetwarzane, wstrzymane, zakończone, anulowane, zwrócone lub zakończone niepowodzeniem. Aktualizacje mogą następować szybko, a kolejność dostawy nie jest bezpiecznym substytutem porównywania znaczników czasu i bieżącego stanu źródła. Spraw, aby powtarzające się przejścia były nieszkodliwe.

Idempotencja jest obowiązkowa w przypadku zdarzeń handlowych

Przekroczenie limitu czasu może nastąpić po zatwierdzeniu przez odbiorcę, ale zanim WooCommerce zobaczy odpowiedź. Ponowna dostawa powoduje wówczas tę samą akcję biznesową, chyba że osoba obsługująca jest idempotentna. Zapisz identyfikator dostawy, jeśli jest obecny. Wymuszaj także unikalność na poziomie domeny, np. jedno żądanie realizacji na każdy sklep i przenoszenie zamówień.

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);
});

Transakcja w skrzynce odbiorczej i nadawczej zapobiega zarówno podwójnej obsłudze, jak i utracie pracy uzupełniającej. Widzieć Ponowna próba webhooka i idempotencja dla pełnego wzoru.

Użyj dzienników WooCommerce, aby debugować stronę nadawcy

WooCommerce rejestruje dostawy webhooków. Otwarte WooCommerce → Status → Dzienniki i filtruj źródło dostarczania elementu webhook opisane w oficjalnej dokumentacji. Porównaj adres URL dostawy, czas żądania, status odpowiedzi i treść odpowiedzi z lokalnym śledzeniem tunelu. Dzienniki nadawców odpowiadają, czy WordPress podjął próbę wykonania żądania; dzienniki odbiornika odpowiadają na to, co zrobiła z nimi aplikacja.

Nie kopiuj niezredagowanego ładunku zamówienia do publikacji publicznej. Może zawierać nazwiska, adresy rozliczeniowe i wysyłkowe, adres e-mail, numer telefonu, wybrane produkty i metadane płatności. Zmniejsz wyposażenie do pól wymaganych do odtworzenia błędu.

Rozwiązywanie typowych błędów webhooka WooCommerce

Element webhook zostanie wyłączony

WooCommerce automatycznie wyłącza webhook po więcej niż pięciu kolejnych nieudanych dostawach. Odpowiedzi poza 2xx, 301 lub 302 liczą się jako niepowodzenia zgodnie z oficjalnym przewodnikiem. Napraw punkt końcowy, ponownie aktywuj webhook i wyślij kontrolowany test. Tak czy inaczej unikaj przekierowań: komplikują one debugowanie podpisów i mogą przypadkowo wysłać podpisane dane klienta do niezamierzonego hosta.

Podpis zawsze się różni

Zahaszuj dokładnie surową treść za pomocą skonfigurowanego sekretu webhooka, zażądaj binarnego wyjścia HMAC, a następnie zakoduj je w Base64. W Node tzn .digest('base64'). Typowe błędy to użycie szesnastkowego, użycie tajnego interfejsu API REST, najpierw przeanalizowanie JSON lub dołączenie dodatkowych bajtów nowej linii.

Początkowy ping działa, ale zdarzenia zamówienia nie

Potwierdź, że wybrany temat jest zgodny z wywołaną akcją. Tworzenie zamówienia i zmiana istniejącego zamówienia to różne tematy. Sprawdź, czy status to Aktywny, sprawdź dzienniki WooCommerce i upewnij się, że wtyczka lub pamięć podręczna pomostowa nie zapobiega przechwyceniu.

Lokalne żądania zwracają 404

Sprawdź pełną ścieżkę, metodę trasy i docelowy port tunelu. WordPress musi POST do /webhooks/woocommerce, a nie tylko początek tunelu. Oprogramowanie pośredniczące platformy nie powinno przekierowywać elementu webhook do zlokalizowanej lub uwierzytelnionej strony.

Przekroczono termin dostaw

Utrzymaj uwierzytelnione zdarzenie i natychmiast zwróć 200 lub 202. Przenieś zdalne wywołania API i ciężkie transformacje do procesu roboczego. Sprawdź, czy lokalne punkty przerwania wstrzymują żądanie na wystarczająco długo, aby można je było sklasyfikować jako niepowodzenie.

Ponowne odtwarzanie ładunku powoduje błąd 401

Przechwycone żądanie musi zawierać dokładne nieprzetworzone bajty i nagłówek podpisu. Edycja JSON unieważnia oryginalny podpis. W przypadku testów logiki biznesowej użyj odkażonego urządzenia za granicą weryfikacji; w przypadku testów kompleksowych wygeneruj nowy HMAC z dedykowanym kluczem tajnym testu. Postępuj zgodnie z bezpieczny przebieg powtórki.

Lista kontrolna bezpieczeństwa danych sklepu lokalnego

• Jeśli to możliwe, przeprowadzaj testy w sklepie przejściowym z klientami i produktami syntetycznymi.
• Użyj unikalnego sekretu webhooka do lokalnego rozwoju i obracaj go po ujawnieniu.
• Sprawdź podpis przed analizowaniem, rejestrowaniem lub umieszczaniem treści w kolejce.
• Oczekiwane źródło i temat sklepu na liście dozwolonych po weryfikacji kryptograficznej.
• Redaguj adresy, dane kontaktowe, uwagi do zamówień i metadane płatności z przechwyconych danych.
• Nigdy nie wyłączaj weryfikacji TLS ani nie udostępniaj odbiorcy danych uwierzytelniających wp-admin.

Architektura lokalna powinna odpowiadać produkcji: transport HTTPS, uwierzytelnianie typu raw-body, trwała akceptacja, przetwarzanie idempotentne, szybka reakcja i możliwe do skontrolowania błędy. W przypadku innego dostawcy handlu z innym nagłówkiem HMAC porównaj plik Lokalny przewodnik po webhooku Shopify.