Làm cách nào để kiểm tra webhook WooCommerce trên localhost?

Hiển thị tuyến POST cục bộ của bạn bằng đường hầm HTTPS, nhập URL công khai của nó vào cài đặt webhook WooCommerce, định cấu hình cùng một bí mật ở cả hai bên và kích hoạt chủ đề đã chọn.

Làm cách nào để xác minh X-WC-Webhook-Signature?

Tính toán HMAC-SHA256 trên nội dung yêu cầu thô chính xác với bí mật webhook đã định cấu hình, mã hóa Base64 thông báo nhị phân và so sánh nó một cách an toàn về mặt thời gian với tiêu đề.

Tại sao WooCommerce vô hiệu hóa webhook của tôi?

WooCommerce vô hiệu hóa webhook sau hơn 5 lần gửi không thành công liên tiếp. Sửa lỗi kết nối, hết thời gian chờ hoặc phản hồi, sau đó kích hoạt lại và kiểm tra lại.

Tôi có thể thấy việc gửi webhook WooCommerce không thành công ở đâu?

Mở WooCommerce → Trạng thái → Nhật ký và lọc nhật ký phân phối webhook. So sánh phản hồi được ghi lại với nhật ký ứng dụng cục bộ và đường hầm của bạn.

Kiểm tra Webhooks WooCommerce trên Localhost

Để kiểm tra webhook WooCommerce trên localhost, hãy hiển thị trình xử lý cục bộ của bạn bằng đường hầm HTTPS, tạo webhook trong WooCommerce → Cài đặt → Nâng cao → Webhooks và xác minh X-WC-Webhook-Signature dưới dạng bản tóm tắt Base64 HMAC-SHA256 của cơ thể thô. Kích hoạt thay đổi đơn hàng hoặc sản phẩm trong cửa hàng thử nghiệm an toàn, kiểm tra việc giao hàng và lặp lại mà không cần triển khai bộ thu.

WooCommerce gửi gì và khi nào

WooCommerce có thể thông báo URL giao hàng khi đơn đặt hàng, sản phẩm, phiếu giảm giá hoặc khách hàng được tạo, cập nhật hoặc xóa. Tiện ích mở rộng có thể thêm chủ đề và nhà phát triển có thể xác định chủ đề tùy chỉnh. Mỗi webhook được định cấu hình có tên, trạng thái, chủ đề, URL phân phối, bí mật và phiên bản API. các tài liệu webhook chính thức của WooCommerce mô tả quá trình tạo, chủ đề, nhật ký phân phối và hành vi lỗi.

Webhook được tự động đính kèm vào một chủ đề chứ không phải vào mọi đột biến lưu trữ. Chọn chủ đề hẹp nhất mà bạn cần tích hợp. Người tiêu dùng được tạo theo đơn đặt hàng cũng không nên xử lý mọi cập nhật sản phẩm. Điều này làm giảm việc tiếp xúc với dữ liệu cá nhân, lưu lượng truy cập và các tác dụng phụ do tai nạn trong quá trình thử nghiệm cục bộ.

Tạo điểm cuối Express nội dung thô

Chữ ký của WooCommerce được tính trên nội dung nó gửi. Bảo toàn các byte đó cho đến khi quá trình xác minh hoàn tất. Tiêu đề chữ ký chứa bản tóm tắt HMAC-SHA256 nhị phân được mã hóa Base64, không phải chuỗi thập lục phân.

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

Trình phân tích cú pháp thô dành riêng cho tuyến đường phải chạy trước trình phân tích cú pháp JSON toàn cầu. Nếu phần mềm trung gian phân tích phần thân trước, việc xâu chuỗi lại đối tượng có thể thay đổi khoảng trắng hoặc thoát và làm mất hiệu lực thông báo. Đây chính là quy tắc về cơ thể thô được đề cập trong hướng dẫn chữ ký webhook, nhưng WooCommerce đặc biệt sử dụng đầu ra Base64.

Bắt đầu đường hầm HTTPS

Khởi động máy thu của bạn và xác nhận nó đang nghe http://localhost:3000.
Chạy npx portpreview 3000 trong một thiết bị đầu cuối thứ hai.
Sao chép URL HTTPS công khai và nối thêm /webhooks/woocommerce.
Giữ cho quá trình chạy trong khi WordPress gửi ping ban đầu và phân phối chủ đề.

Máy chủ WordPress—không phải trình duyệt nơi bạn mở wp-admin—phải có khả năng truy cập URL công khai. Một đường hầm kết nối yêu cầu công khai với quá trình phát triển riêng tư của bạn. Nó cũng cung cấp TLS đáng tin cậy, do đó bạn không cần phải lộ cổng bộ định tuyến hoặc cài đặt chứng chỉ công khai của riêng mình.

Định cấu hình webhook trong WooCommerce

Mở WooCommerce → Cài đặt → Nâng cao → Webhooks.
Lựa chọn Thêm webhook và đặt cho nó một cái tên phát triển địa phương dễ nhận biết.
Chọn Tích cực trạng thái và một chủ đề cụ thể, chẳng hạn như Đơn hàng đã được tạo.
Dán URL phân phối đường hầm đầy đủ.
Tạo một bí mật ngẫu nhiên dài và đặt giá trị giống hệt nhau vào WC_WEBHOOK_SECRET.
Lưu webhook, sau đó kích hoạt chủ đề trong cửa hàng thử nghiệm.

Khi một webhook đang hoạt động được lưu lần đầu tiên, WooCommerce sẽ gửi ping đến URL phân phối. Ping xác nhận kết nối nhưng không thay thế cho tải trọng đơn hàng thực. Làm cho điểm cuối của bạn chấp nhận yêu cầu ban đầu, sau đó tạo hoặc cập nhật dữ liệu thử nghiệm để thực hiện chủ đề đã chọn.

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

Nếu bạn dán bí mật Base64 vào tệp môi trường, hãy trích dẫn nó để giữ nguyên dấu câu. Bí mật là khóa HMAC; Khóa tiêu dùng API REST của WooCommerce và mật khẩu WordPress là thông tin xác thực không liên quan.

Sử dụng tiêu đề để định tuyến và theo dõi việc giao hàng

WooCommerce bao gồm các tiêu đề siêu dữ liệu hữu ích. Tùy thuộc vào phiên bản và môi trường, chúng bao gồm chủ đề, tài nguyên, sự kiện, nguồn, ID webhook và ID phân phối. Xử lý tên không phân biệt chữ hoa chữ thường theo yêu cầu của HTTP. Sử dụng chủ đề cho công văn và ID giao hàng để truy nguyên, nhưng luôn xác thực nội dung trước.

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

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

Đừng suy luận chủ đề chỉ từ hình dạng JSON. Một đơn hàng được tạo và tải trọng được cập nhật của đơn hàng có thể trông giống nhau, trong khi hành động xuôi dòng chính xác lại khác. Ngược lại, từ chối kết hợp tiêu đề/chủ đề mà điểm cuối của bạn chưa bao giờ được định cấu hình để chấp nhận.

Xử lý khối lượng đơn đặt hàng một cách phòng thủ

Sử dụng số nhận dạng bất biến

Tương quan các bản ghi theo danh tính cửa hàng và ID đối tượng WooCommerce, không phải định dạng số đơn hàng, email khách hàng hoặc tên hiển thị. Cả hai cửa hàng đều có thể có ID đơn hàng 42, vì vậy việc tích hợp nhiều cửa hàng cần có khóa ghép.

Mong đợi các phần mở rộng để thay đổi các trường

Các tiện ích mở rộng thanh toán, đăng ký, thuế, thanh toán và thực hiện có thể thêm các trường siêu dữ liệu và mục hàng. Xác thực các trường mà logic nghiệp vụ của bạn yêu cầu, bỏ qua các trường không xác định và lưu phiên bản lược đồ hoặc bản cố định được xử lý lại tối thiểu để kiểm tra hồi quy.

Tách biệt biên nhận sự kiện với việc thực hiện

Webhook cho biết đơn hàng đã thay đổi sẽ được đưa vào hàng đợi hoặc hộp thư đến lâu dài. Đồng bộ hóa hàng tồn kho, nhãn vận chuyển, cuộc gọi ERP và email khách hàng sẽ chạy sau khi xác nhận. Điều này ngăn chặn sự phụ thuộc chậm khiến WooCommerce hiểu biên nhận thành công là giao hàng không thành công.

Cập nhật mô hình khi chuyển đổi trạng thái

Đơn đặt hàng có thể chuyển qua các trạng thái đang chờ xử lý, đang xử lý, tạm dừng, đã hoàn thành, bị hủy, hoàn tiền hoặc không thành công. Cập nhật có thể diễn ra nhanh chóng và thứ tự giao hàng không phải là sự thay thế an toàn để so sánh dấu thời gian và trạng thái nguồn hiện tại. Làm cho việc chuyển đổi lặp đi lặp lại trở nên vô hại.

Quyền bình đẳng là bắt buộc đối với các sự kiện thương mại

Thời gian chờ có thể xảy ra sau khi người nhận của bạn cam kết nhưng trước khi WooCommerce thấy phản hồi. Sau đó, việc phân phối lại sẽ tạo ra hành động kinh doanh tương tự trừ khi người xử lý không có quyền. Lưu trữ ID giao hàng nếu có. Đồng thời thực thi tính duy nhất ở cấp miền, chẳng hạn như một yêu cầu thực hiện cho mỗi cửa hàng và chuyển đổi đơn hàng.

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

Giao dịch hộp thư đến và hộp thư đi ngăn chặn cả việc xử lý trùng lặp và mất công việc tiếp theo. Nhìn thấy thử lại webhook và bình thường cho mẫu đầy đủ.

Sử dụng nhật ký WooCommerce để gỡ lỗi phía người gửi

WooCommerce ghi lại việc gửi webhook. Mở WooCommerce → Trạng thái → Nhật ký và lọc nguồn phân phối webhook được mô tả trong tài liệu chính thức. So sánh URL phân phối, thời gian yêu cầu, trạng thái phản hồi và nội dung phản hồi với dấu vết đường hầm cục bộ của bạn. Nhật ký người gửi trả lời liệu WordPress có thử yêu cầu hay không; nhật ký người nhận trả lời ứng dụng của bạn đã làm gì với nó.

Không sao chép trọng tải đơn đặt hàng chưa được xác minh vào một vấn đề công khai. Nó có thể chứa tên, địa chỉ thanh toán và giao hàng, email, số điện thoại, lựa chọn sản phẩm và siêu dữ liệu thanh toán. Giảm bản sửa lỗi xuống các trường bắt buộc để tái tạo lỗi.

Khắc phục sự cố phổ biến của webhook WooCommerce

Webhook bị vô hiệu hóa

WooCommerce tự động vô hiệu hóa webhook sau hơn năm lần gửi liên tiếp. Các phản hồi bên ngoài 2xx, 301 hoặc 302 được tính là không thành công theo hướng dẫn chính thức. Sửa điểm cuối, kích hoạt lại webhook và gửi bài kiểm tra có kiểm soát. Dù sao thì hãy tránh chuyển hướng: chúng làm phức tạp việc gỡ lỗi chữ ký và có thể vô tình gửi dữ liệu khách hàng đã ký đến một máy chủ ngoài ý muốn.

Chữ ký luôn khác nhau

Băm phần nội dung thô chính xác với bí mật được định cấu hình của webhook, yêu cầu đầu ra HMAC nhị phân, sau đó mã hóa Base64. Trong Node, đó là .digest('base64'). Các lỗi phổ biến là sử dụng hệ thập lục phân, sử dụng bí mật API REST, phân tích cú pháp JSON trước hoặc bao gồm các byte dòng mới bổ sung.

Ping ban đầu hoạt động nhưng các sự kiện đặt hàng thì không

Xác nhận chủ đề đã chọn phù hợp với hành động bạn đã kích hoạt. Tạo đơn hàng và thay đổi đơn hàng hiện có là những chủ đề khác nhau. Xác minh trạng thái là Đang hoạt động, kiểm tra nhật ký WooCommerce và đảm bảo plugin hoặc bộ đệm tạm thời không ngăn chặn hook cơ bản.

Yêu cầu cục bộ trả về 404

Kiểm tra đường dẫn đầy đủ, phương thức định tuyến và cổng mục tiêu đường hầm. WordPress phải POST lên /webhooks/woocommerce, không chỉ đơn thuần là nguồn gốc đường hầm. Phần mềm trung gian khung không được chuyển hướng webhook đến một trang được bản địa hóa hoặc xác thực.

Hết thời gian giao hàng

Duy trì sự kiện đã được xác thực và trả lại 200 hoặc 202 ngay lập tức. Di chuyển các lệnh gọi API từ xa và các chuyển đổi nặng sang một công nhân. Kiểm tra xem các điểm dừng cục bộ có tạm dừng yêu cầu đủ lâu để được phân loại là lỗi hay không.

Việc phát lại tải trọng gây ra lỗi 401

Yêu cầu được ghi lại phải giữ lại byte thô và tiêu đề chữ ký chính xác. Chỉnh sửa JSON làm mất hiệu lực chữ ký gốc. Đối với các thử nghiệm logic nghiệp vụ, hãy sử dụng thiết bị cố định đã được vệ sinh sau ranh giới xác minh; đối với các thử nghiệm toàn diện, hãy tạo HMAC mới với bí mật thử nghiệm chuyên dụng. Theo dõi quy trình phát lại an toàn.

Danh sách kiểm tra bảo mật cho dữ liệu cửa hàng địa phương

Thử nghiệm trên một cửa hàng dàn dựng với khách hàng và sản phẩm tổng hợp bất cứ khi nào có thể.
Sử dụng một bí mật webhook duy nhất để phát triển cục bộ và xoay nó sau khi hiển thị.
Xác minh chữ ký trước khi phân tích cú pháp, ghi nhật ký hoặc xếp hàng nội dung.
Nguồn và chủ đề lưu trữ dự kiến trong danh sách cho phép sau khi xác minh bằng mật mã.
Biên tập lại địa chỉ, chi tiết liên hệ, ghi chú đặt hàng và siêu dữ liệu thanh toán từ các bản chụp.
Không bao giờ vô hiệu hóa xác minh TLS hoặc hiển thị thông tin xác thực wp-admin cho người nhận.

Kiến trúc cục bộ phải phù hợp với quá trình sản xuất: vận chuyển HTTPS, xác thực nội dung thô, chấp nhận bền vững, xử lý bình thường, phản hồi nhanh và các lỗi có thể kiểm tra được. Đối với nhà cung cấp thương mại khác có tiêu đề HMAC khác, hãy so sánh Hướng dẫn webhook địa phương của Shopify.