Як перевірити веб-хуки WooCommerce на локальному хості?

Відкрийте свій локальний маршрут POST за допомогою тунелю HTTPS, введіть його загальнодоступну URL-адресу в налаштуваннях вебхука WooCommerce, налаштуйте однаковий секрет з обох сторін і запустіть вибрану тему.

Як перевірити X-WC-Webhook-Signature?

Обчисліть HMAC-SHA256 над точним необробленим тілом запиту з налаштованим секретом вебхуку, закодуйте двійковий дайджест за допомогою Base64 і порівняйте його за часом із заголовком.

Чому WooCommerce вимкнув мій вебхук?

WooCommerce вимикає вебхук після більш ніж п’яти послідовних помилок доставки. Виправте помилки підключення, тайм-ауту або відповіді, а потім повторно активуйте його та перевірте знову.

Де я можу переглянути невдалі доставки вебхуку WooCommerce?

Відкрийте WooCommerce → Статус → Журнали та відфільтруйте журнали доставки вебхуків. Порівняйте записану відповідь із журналами вашого тунелю та локальної програми.

Перевірте вебхуки WooCommerce на Localhost

Щоб протестувати веб-хуки WooCommerce на локальному хості, відкрийте локальний обробник за допомогою тунелю HTTPS, створіть веб-хук у WooCommerce → Налаштування → Додатково → Веб-хуки та перевірте X-WC-Webhook-Signature як дайджест Base64 HMAC-SHA256 необробленого тіла. Запустіть замовлення або змініть продукт у безпечному тестовому магазині, перевірте доставку та повторіть без розгортання приймача.

Що і коли надсилає WooCommerce

WooCommerce може повідомляти URL-адресу доставки, коли замовлення, продукти, купони або клієнти створюються, оновлюються чи видаляються. Розширення можуть додавати теми, а розробники можуть визначати спеціальні теми. Кожен налаштований вебхук має назву, статус, тему, URL-адресу доставки, секрет і версію API. офіційна документація вебхуку WooCommerce описує створення, теми, журнали доставки та поведінку збоїв.

Вебхук приєднується до теми, а не до кожної зміни магазину автоматично. Виберіть найвужчу тему, яка потрібна вашій інтеграції. Споживач, створений за замовленням, не повинен обробляти кожне оновлення продукту. Це зменшує доступ до персональних даних, трафік і випадкові побічні ефекти під час локального тестування.

Створіть кінцеву точку Express із сирим тілом

Підпис WooCommerce обчислюється над тілом, яке він надсилає. Зберігайте ці байти до завершення перевірки. Заголовок підпису містить двійковий дайджест HMAC-SHA256 у кодуванні Base64, а не шістнадцятковий рядок.

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

Синтаксичний аналізатор необроблених даних для конкретного маршруту має запускатися перед глобальним аналізатором JSON. Якщо проміжне програмне забезпечення спочатку аналізує тіло, повторна утворення рядків об’єкта може змінити пробіли або екранування та зробити дайджест недійсним. Це те саме правило необробленого тіла, описане в посібник із підпису вебхука, але WooCommerce спеціально використовує вивід Base64.

Запустіть тунель HTTPS

Запустіть приймач і переконайтеся, що він прослуховується http://localhost:3000.
бігти npx portpreview 3000 у другому терміналі.
Скопіюйте загальнодоступну URL-адресу HTTPS і додайте /webhooks/woocommerce.
Підтримуйте процес, поки WordPress надсилає свій початковий ping і відправляє тему.

Хост WordPress, а не браузер, у якому ви відкрили wp-admin, має мати можливість отримати доступ до загальнодоступної URL-адреси. Тунель з’єднує цей публічний запит із вашим приватним процесом розробки. Він також забезпечує надійний TLS, тому вам не потрібно відкривати порт маршрутизатора або встановлювати власний публічний сертифікат.

Налаштуйте вебхук у WooCommerce

ВІДЧИНЕНО WooCommerce → Налаштування → Додатково → Веб-хуки.
Виберіть Додати вебхук і дайте йому впізнавану назву місцевого розвитку.
Виберіть Активний статус і конкретну тему, наприклад замовлення створено.
Вставте повну URL-адресу доставки тунелю.
Згенеруйте довгий випадковий секрет і вставте в нього ідентичне значення WC_WEBHOOK_SECRET.
Збережіть вебхук, а потім запустіть тему в тестовому магазині.

Коли активний вебхук зберігається вперше, WooCommerce надсилає запит ping на URL-адресу доставки. Пінг підтверджує підключення, але не замінює справжнє корисне навантаження замовлення. Зробіть вашу кінцеву точку терпимою до початкового запиту, а потім створіть або оновіть тестові дані для виконання вибраної теми.

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

Якщо ви вставляєте секрет Base64 у файл середовища, візьміть його в лапки, щоб зберегти пунктуацію. Секрет полягає в ключі HMAC; Ключі користувача WooCommerce REST API та паролі WordPress не пов’язані облікові дані.

Використовуйте заголовки для маршрутизації та відстеження доставки

WooCommerce містить корисні заголовки метаданих. Залежно від версії та середовища, це включає тему, ресурс, подію, джерело, ідентифікатор вебхука та ідентифікатор доставки. Не враховуйте регістр імен, як того вимагає HTTP. Використовуйте тему для відправки та ідентифікатор доставки для відстеження, але завжди спочатку автентифікуйте тіло.

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

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

Не виводьте тему лише з форми JSON. Створене замовлення та оновлене корисне навантаження можуть виглядати подібно, тоді як правильна дія нижче за потоком відрізняється. І навпаки, відхиліть комбінацію заголовка/теми, яку ваша кінцева точка ніколи не налаштовувала на прийняття.

Обробляйте корисні навантаження замовлення в захисті

Використовуйте незмінні ідентифікатори

Співвідносьте записи за ідентифікатором магазину та ідентифікатором об’єкта WooCommerce, а не за форматуванням номера замовлення, електронною адресою клієнта чи відображуваними іменами. Обидва магазини можуть мати ідентифікатор замовлення 42, тому для інтеграції кількох магазинів потрібен складений ключ.

Очікуйте розширення для зміни полів

Розширення оплати, підписки, податку, оформлення замовлення та виконання можуть додавати метадані та поля рядків-позицій. Перевірте поля, які вимагає ваша бізнес-логіка, ігноруйте невідомі поля та збережіть версію схеми або мінімально відредагований фікстур для регресійних тестів.

Окрема подія отримання від виконання

Вебхук із сповіщенням про зміну замовлення має потрапити в стійку чергу або вхідні. Синхронізація інвентаризації, транспортних етикеток, викликів ERP та електронної пошти клієнта мають запускатися після підтвердження. Це запобігає повільній залежності від того, щоб WooCommerce інтерпретував успішне отримання як невдалу доставку.

Оновлення моделі як зміни стану

Замовлення може проходити через стан очікування, обробки, очікування, завершення, скасування, відшкодування або невдачу. Оновлення можуть відбуватися швидко, і порядок доставки не є безпечною заміною для порівняння часових позначок і поточного стану джерела. Зробіть повторні переходи нешкідливими.

Ідемпотентність є обов'язковою для комерційних подій

Тайм-аут може статися після того, як ваш одержувач фіксує, але до того, як WooCommerce побачить відповідь. Потім повторна доставка створює ту саму бізнес-дію, якщо обробник не є ідемпотентним. Зберігайте ідентифікатор доставки, якщо він є. Також забезпечте унікальність на рівні домену, наприклад, один запит на виконання на магазин і перехід замовлення.

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

Транзакція «Вхідні та вихідні» запобігає обробці дублікатів і втраті подальшої роботи. див повторна спроба вебхука та ідемпотентність для повного малюнка.

Використовуйте журнали WooCommerce для налагодження сторони відправника

WooCommerce реєструє доставку через вебхук. ВІДЧИНЕНО WooCommerce → Статус → Журнали і фільтр для джерела доставки webhook, описаного в офіційній документації. Порівняйте URL-адресу доставки, час запиту, статус відповіді та тіло відповіді з локальним трасуванням тунелю. Журнали відправника відповідають, чи спробував WordPress надіслати запит; журнали приймачів відповідають, що ваша програма зробила з ним.

Не копіюйте невідредагований корисний навантаження замовлення в загальнодоступний випуск. Він може містити імена, адреси виставлення рахунків і доставки, електронну адресу, номер телефону, вибір продуктів і метадані платежу. Зменшіть прилад до полів, необхідних для відтворення помилки.

Усунення поширених збоїв вебхуку WooCommerce

Вебхук стає вимкненим

WooCommerce автоматично вимикає вебхук після більш ніж п’яти послідовних помилок доставки. Відповіді за межами 2xx, 301 або 302 вважаються помилками згідно з офіційним посібником. Виправте кінцеву точку, повторно активуйте вебхук і надішліть контрольований тест. У будь-якому випадку уникайте переспрямувань: вони ускладнюють налагодження підпису та можуть випадково надіслати підписані дані клієнта на ненавмисний хост.

Підпис завжди відрізняється

Хешуйте точне необроблене тіло з налаштованим секретом вебхука, запитайте двійковий вихід HMAC, а потім закодуйте його за допомогою Base64. У Node, тобто .digest('base64'). Типовими помилками є використання шістнадцяткового коду, використання секрету REST API, розбір JSON спочатку або включення додаткових байтів нового рядка.

Початковий ping працює, але події порядку ні

Підтвердьте, що вибрана тема відповідає дії, яку ви ініціювали. Створення замовлення та зміна існуючого замовлення – це різні теми. Перевірте статус «Активний», перевірте журнали WooCommerce і переконайтеся, що плагін або проміжний кеш не перешкоджає базовому хуку.

Локальні запити повертають 404

Перевірте повний шлях, метод маршруту та цільовий порт тунелю. WordPress має ПУБЛІКУВАТИ на /webhooks/woocommerce, а не лише походження тунелю. Проміжне програмне забезпечення Framework не повинно перенаправляти вебхук на локалізовану або автентифіковану сторінку.

Тайм-аут доставки

Зберігати автентифіковану подію та негайно повертати 200 або 202. Перемістіть віддалені виклики API та важкі перетворення до робочого. Перевірте, чи локальні точки зупину призупиняють запит достатньо довго, щоб його класифікували як помилку.

Повторне відтворення корисного навантаження викликає помилку 401

Захоплений запит повинен зберігати точні необроблені байти та заголовок підпису. Редагування JSON робить оригінальний підпис недійсним. Для тестів бізнес-логіки використовуйте продезінфікований прилад після межі перевірки; для наскрізних тестів згенеруйте новий HMAC із спеціальним тестовим секретом. Дотримуйтесь робочий процес безпечного відтворення.

Контрольний список безпеки для даних локального сховища

Тестуйте в демонстраційному магазині з синтетичними клієнтами та продуктами, коли це можливо.
Використовуйте унікальний секрет вебхуку для локальної розробки та змінюйте його після показу.
Перевірте підпис перед синтаксичним аналізом, записом у журнал або розміщенням тіла в черзі.
Очікуване джерело та тему білого списку після криптографічної перевірки.
Видаліть адреси, контактні дані, примітки до замовлень і метадані платежів із записів.
Ніколи не вимикайте перевірку TLS і не надавайте облікові дані wp-admin одержувачу.

Локальна архітектура має відповідати продуктивності: транспортування HTTPS, автентифікація необробленого тіла, тривале прийняття, ідемпотентна обробка, швидка реакція та помилки, які можна перевірити. Для іншого комерційного постачальника з іншим заголовком HMAC порівняйте Локальний посібник із вебхуку Shopify.