ทดสอบ WooCommerce Webhooks บน Localhost

หากต้องการทดสอบ WooCommerce webhooks บน localhost ให้เปิดเผยตัวจัดการในเครื่องของคุณด้วยอุโมงค์ HTTPS สร้าง webhook ภายใต้ WooCommerce → การตั้งค่า → ขั้นสูง → Webhooks และตรวจสอบ X-WC-Webhook-Signature เป็น Base64 HMAC-SHA256 ย่อยของตัวดิบ กระตุ้นคำสั่งซื้อหรือการเปลี่ยนแปลงผลิตภัณฑ์ในร้านทดสอบที่ปลอดภัย ตรวจสอบการจัดส่ง และทำซ้ำโดยไม่ต้องปรับใช้ตัวรับ

WooCommerce ส่งอะไรและเมื่อใด

WooCommerce สามารถแจ้ง URL การจัดส่งเมื่อมีการสร้าง อัปเดต หรือลบคำสั่งซื้อ สินค้า คูปอง หรือลูกค้า ส่วนขยายสามารถเพิ่มหัวข้อได้ และนักพัฒนาสามารถกำหนดหัวข้อที่กำหนดเองได้ Webhook ที่กำหนดค่าแต่ละรายการจะมีชื่อ สถานะ หัวข้อ URL การนำส่ง ข้อมูลลับ และเวอร์ชัน API ที่ เอกสาร webhook อย่างเป็นทางการของ WooCommerce อธิบายการสร้าง หัวข้อ บันทึกการจัดส่ง และพฤติกรรมความล้มเหลว

มีการแนบเว็บฮุคเข้ากับหัวข้อ ไม่ใช่กับการเปลี่ยนแปลงร้านค้าทุกครั้งโดยอัตโนมัติ เลือกหัวข้อที่แคบที่สุดที่คุณต้องการในการบูรณาการ ผู้บริโภคที่สร้างคำสั่งซื้อไม่ควรประมวลผลการอัปเดตผลิตภัณฑ์ทุกครั้ง ซึ่งจะช่วยลดการเปิดเผยข้อมูลส่วนบุคคล การรับส่งข้อมูล และผลข้างเคียงจากอุบัติเหตุระหว่างการทดสอบในพื้นที่

สร้างปลายทาง Express ของเนื้อหาดิบ

ลายเซ็นของ WooCommerce จะถูกคำนวณในส่วนเนื้อหาที่ส่ง รักษาไบต์เหล่านั้นไว้จนกว่าการตรวจสอบจะเสร็จสิ้น ส่วนหัวของลายเซ็นประกอบด้วยไบนารีที่เข้ารหัส Base64 HMAC-SHA256 ย่อย ไม่ใช่สตริงเลขฐานสิบหก

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 ส่วนกลาง หากมิดเดิลแวร์แยกวิเคราะห์เนื้อหาก่อน การสตริงวัตถุอีกครั้งอาจเปลี่ยนช่องว่างหรือการหลบหนีและทำให้การแยกย่อยไม่ถูกต้อง นี่เป็นกฎเนื้อดิบเดียวกันที่ครอบคลุมใน คู่มือลายเซ็น Webhookแต่ WooCommerce ใช้เอาต์พุต Base64 โดยเฉพาะ

เริ่มต้นอุโมงค์ HTTPS

1. เริ่มเครื่องรับของคุณและยืนยันว่าเครื่องฟังอยู่ http://localhost:3000.
2. วิ่ง npx portpreview 3000 ในเทอร์มินัลที่สอง
3. คัดลอก HTTPS URL สาธารณะแล้วผนวก /webhooks/woocommerce.
4. ให้กระบวนการทำงานต่อไปในขณะที่ WordPress ส่ง Ping เริ่มต้นและการจัดส่งหัวข้อ

โฮสต์ WordPress ไม่ใช่เบราว์เซอร์ที่คุณเปิด wp-admin จะต้องสามารถเข้าถึง URL สาธารณะได้ อุโมงค์เชื่อมคำขอสาธารณะกับกระบวนการพัฒนาส่วนตัวของคุณ นอกจากนี้ยังมี TLS ที่เชื่อถือได้ ดังนั้นคุณไม่จำเป็นต้องเปิดเผยพอร์ตเราเตอร์หรือติดตั้งใบรับรองสาธารณะของคุณเอง

กำหนดค่า webhook ใน WooCommerce

1. เปิด WooCommerce → การตั้งค่า → ขั้นสูง → Webhooks.
2. เลือก เพิ่มเว็บฮุค และตั้งชื่อการพัฒนาท้องถิ่นให้เป็นที่รู้จัก
3. เลือก คล่องแคล่ว สถานะและหัวข้อเฉพาะ เช่น คำสั่งซื้อที่สร้าง
4. วาง URL การนำส่งช่องสัญญาณแบบเต็ม
5. สร้างความลับแบบสุ่มขนาดยาวและวางค่าที่เหมือนกันลงไป WC_WEBHOOK_SECRET.
6. บันทึก webhook จากนั้นทริกเกอร์หัวข้อในร้านค้าทดสอบ

เมื่อมีการบันทึก webhook ที่ใช้งานอยู่เป็นครั้งแรก WooCommerce จะส่ง Ping ไปยัง URL การนำส่ง การ ping ยืนยันการเชื่อมต่อ แต่ไม่สามารถทดแทนเพย์โหลดการสั่งซื้อจริงได้ ทำให้ตำแหน่งข้อมูลของคุณยอมรับคำขอเริ่มต้น จากนั้นสร้างหรืออัปเดตข้อมูลทดสอบเพื่อใช้หัวข้อที่เลือก

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 เท่านั้น คำสั่งซื้อที่สร้างขึ้นและเพย์โหลดที่อัปเดตของคำสั่งซื้ออาจมีลักษณะคล้ายกัน ในขณะที่การดำเนินการดาวน์สตรีมที่ถูกต้องจะแตกต่างออกไป ในทางกลับกัน ให้ปฏิเสธการรวมส่วนหัว/หัวข้อที่ปลายทางของคุณไม่เคยได้รับการกำหนดค่าให้ยอมรับ

ประมวลผลเพย์โหลดการสั่งซื้อในเชิงป้องกัน

ใช้ตัวระบุที่ไม่เปลี่ยนรูป

เชื่อมโยงบันทึกตามข้อมูลประจำตัวของร้านค้าและ ID ออบเจ็กต์ WooCommerce ไม่ใช่การจัดรูปแบบหมายเลขคำสั่งซื้อ อีเมลของลูกค้า หรือชื่อที่แสดง ร้านค้าสองแห่งสามารถมีรหัสคำสั่งซื้อ 42 ได้ทั้งคู่ ดังนั้นการผสานรวมร้านค้าหลายร้านจึงจำเป็นต้องมีคีย์ผสม

คาดว่าส่วนขยายจะเปลี่ยนแปลงฟิลด์

ส่วนขยายการชำระเงิน การสมัครสมาชิก ภาษี การชำระเงิน และการดำเนินการตามคำสั่งซื้อสามารถเพิ่มช่องข้อมูลเมตาและบรรทัดรายการได้ ตรวจสอบฟิลด์ที่ตรรกะทางธุรกิจของคุณต้องการ ละเว้นฟิลด์ที่ไม่รู้จัก และบันทึกเวอร์ชันสคีมาหรือฟิกซ์เจอร์ที่แก้ไขขั้นต่ำสำหรับการทดสอบการถดถอย

แยกการรับเหตุการณ์ออกจากการปฏิบัติตาม

เว็บฮุคที่บอกว่าคำสั่งซื้อมีการเปลี่ยนแปลงควรเข้าสู่คิวหรือกล่องจดหมายแบบถาวร การซิงโครไนซ์สินค้าคงคลัง ป้ายกำกับการจัดส่ง การโทร ERP และอีเมลลูกค้าควรทำงานหลังจากการตอบรับ สิ่งนี้จะป้องกันการพึ่งพาที่ช้าจากการทำให้ WooCommerce ตีความการรับที่สำเร็จว่าเป็นการจัดส่งที่ล้มเหลว

การอัปเดตโมเดลเป็นการเปลี่ยนสถานะ

คำสั่งซื้ออาจผ่านสถานะรอดำเนินการ ประมวลผล ระงับ เสร็จสมบูรณ์ ยกเลิก ขอเงินคืน หรือล้มเหลว การอัปเดตสามารถเกิดขึ้นได้อย่างรวดเร็ว และลำดับการจัดส่งไม่ใช่สิ่งทดแทนที่ปลอดภัยสำหรับการเปรียบเทียบการประทับเวลาและสถานะแหล่งที่มาปัจจุบัน ทำให้การเปลี่ยนภาพซ้ำๆ ไม่เป็นอันตราย

Idempotency เป็นสิ่งจำเป็นสำหรับกิจกรรมการค้า

การหมดเวลาสามารถเกิดขึ้นได้หลังจากที่ผู้รับของคุณกระทำ แต่ก่อนที่ 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);
});

ธุรกรรมกล่องจดหมายเข้าและกล่องจดหมายออกช่วยป้องกันทั้งการจัดการที่ซ้ำกันและการสูญเสียงานติดตามผล ดู ลอง webhook อีกครั้งและ idempotency เพื่อรูปแบบที่สมบูรณ์

ใช้บันทึก WooCommerce เพื่อดีบักฝั่งผู้ส่ง

WooCommerce บันทึกการส่งมอบ webhook เปิด WooCommerce → สถานะ → บันทึก และกรองแหล่งที่มาการนำส่ง webhook ที่อธิบายไว้ในเอกสารประกอบอย่างเป็นทางการ เปรียบเทียบ URL การส่ง เวลาคำขอ สถานะการตอบกลับ และเนื้อหาการตอบกลับกับการติดตามอุโมงค์ในเครื่องของคุณ บันทึกของผู้ส่งตอบว่า WordPress พยายามร้องขอหรือไม่ บันทึกของผู้รับจะตอบสิ่งที่แอปพลิเคชันของคุณทำกับมัน

อย่าคัดลอกเพย์โหลดคำสั่งซื้อที่ยังไม่ได้แก้ไขไปเป็นประเด็นสาธารณะ โดยอาจประกอบด้วยชื่อ ที่อยู่สำหรับการเรียกเก็บเงินและที่อยู่สำหรับจัดส่ง อีเมล โทรศัพท์ ตัวเลือกผลิตภัณฑ์ และข้อมูลเมตาการชำระเงิน ลดฟิกซ์เจอร์ลงในฟิลด์ที่จำเป็นในการสร้างจุดบกพร่องอีกครั้ง

แก้ไขปัญหาความล้มเหลวของเว็บฮุค WooCommerce ทั่วไป

เว็บฮุคถูกปิดใช้งาน

WooCommerce ปิดใช้งาน webhook โดยอัตโนมัติหลังจากการส่งมอบล้มเหลวติดต่อกันมากกว่าห้าครั้ง การตอบกลับภายนอก 2xx, 301 หรือ 302 ถือเป็นความล้มเหลวตามคำแนะนำอย่างเป็นทางการ แก้ไขปลายทาง เปิดใช้งานเว็บฮุคอีกครั้ง และส่งการทดสอบที่มีการควบคุม หลีกเลี่ยงการเปลี่ยนเส้นทางอยู่แล้ว เนื่องจากจะทำให้การดีบักลายเซ็นซับซ้อนขึ้น และอาจส่งข้อมูลลูกค้าที่ลงนามไปยังโฮสต์ที่ไม่ได้ตั้งใจโดยไม่ตั้งใจ

ลายเซ็นจะแตกต่างเสมอ

แฮชเนื้อหาดิบที่แน่นอนด้วยข้อมูลลับที่กำหนดค่าของ webhook ขอเอาต์พุต HMAC แบบไบนารี จากนั้นเข้ารหัส Base64 ในโหนดนั่นคือ .digest('base64'). ข้อผิดพลาดทั่วไปคือการใช้เลขฐานสิบหก ใช้ข้อมูลลับ REST API แยกวิเคราะห์ JSON ก่อน หรือรวมไบต์ขึ้นบรรทัดใหม่เพิ่มเติม

การ ping เริ่มต้นใช้งานได้ แต่เหตุการณ์การสั่งซื้อไม่ทำงาน

ยืนยันว่าหัวข้อที่เลือกตรงกับการกระทำที่คุณทริกเกอร์ การสร้างคำสั่งซื้อและการเปลี่ยนแปลงคำสั่งซื้อที่มีอยู่เป็นหัวข้อที่แตกต่างกัน ตรวจสอบว่าสถานะเป็นใช้งานอยู่ ตรวจสอบบันทึก WooCommerce และตรวจสอบให้แน่ใจว่าปลั๊กอินหรือแคชชั่วคราวไม่ได้ป้องกันฮุคที่ซ่อนอยู่

คำขอในท้องถิ่นส่งคืน 404

ตรวจสอบเส้นทางแบบเต็ม วิธีเส้นทาง และพอร์ตเป้าหมายทันเนล WordPress ต้องโพสต์ไปที่ /webhooks/woocommerceไม่ใช่เพียงต้นกำเนิดของอุโมงค์เท่านั้น มิดเดิลแวร์เฟรมเวิร์กไม่ควรเปลี่ยนเส้นทาง webhook ไปยังหน้าที่แปลหรือได้รับการรับรองความถูกต้อง

หมดเวลาจัดส่ง

ยืนยันเหตุการณ์ที่ได้รับการรับรองความถูกต้องและส่งกลับ 200 หรือ 202 ทันที ย้ายการเรียก API ระยะไกลและการเปลี่ยนแปลงจำนวนมากไปยังผู้ปฏิบัติงาน ตรวจสอบว่าเบรกพอยต์เฉพาะที่หยุดการร้องขอชั่วคราวนานพอที่จะจัดว่าเป็นความล้มเหลวหรือไม่

การเล่นซ้ำเพย์โหลดทำให้เกิด 401

คำขอที่บันทึกต้องคงไบต์ดิบและส่วนหัวของลายเซ็นไว้ การแก้ไข JSON จะทำให้ลายเซ็นต้นฉบับเป็นโมฆะ สำหรับการทดสอบตรรกะทางธุรกิจ ให้ใช้ฟิกซ์เจอร์ที่ผ่านการฆ่าเชื้อหลังขอบเขตการตรวจสอบ สำหรับการทดสอบแบบ end-to-end ให้สร้าง HMAC ใหม่พร้อมข้อมูลลับการทดสอบเฉพาะ ติดตาม ขั้นตอนการเล่นซ้ำอย่างปลอดภัย.

รายการตรวจสอบความปลอดภัยสำหรับข้อมูลร้านค้าในพื้นที่

• ทดสอบกับลูกค้าและผลิตภัณฑ์สังเคราะห์ในร้านค้าชั่วคราวทุกครั้งที่เป็นไปได้
• ใช้ความลับของเว็บฮุคที่ไม่ซ้ำใครเพื่อการพัฒนาในพื้นที่และหมุนเวียนข้อมูลดังกล่าวหลังจากการเปิดเผย
• ตรวจสอบลายเซ็นก่อนแยกวิเคราะห์ บันทึก หรือจัดคิวเนื้อหา
• อนุญาตแหล่งที่มาและหัวข้อของร้านค้าที่คาดหวังหลังการยืนยันการเข้ารหัส
• ปกปิดที่อยู่ รายละเอียดการติดต่อ บันทึกการสั่งซื้อ และข้อมูลเมตาการชำระเงินจากการจับกุม
• อย่าปิดใช้งานการตรวจสอบ TLS หรือเปิดเผยข้อมูลรับรอง wp-admin แก่ผู้รับ

สถาปัตยกรรมภายในเครื่องควรตรงกับการใช้งานจริง: การขนส่ง HTTPS, การตรวจสอบสิทธิ์เนื้อหาดิบ, การยอมรับแบบคงทน, การประมวลผลแบบ idempotent, การตอบสนองที่รวดเร็ว และความล้มเหลวที่ตรวจสอบได้ สำหรับผู้ให้บริการการค้ารายอื่นที่มีส่วนหัว HMAC ที่แตกต่างกัน ให้เปรียบเทียบ คู่มือเว็บฮุคท้องถิ่นของ Shopify.