लोकलहोस्ट पर WooCommerce वेबहुक का परीक्षण करें

लोकलहोस्ट पर WooCommerce वेबहुक का परीक्षण करने के लिए, अपने स्थानीय हैंडलर को HTTPS टनल के साथ उजागर करें, WooCommerce → सेटिंग्स → एडवांस्ड → वेबहुक के तहत एक वेबहुक बनाएं और सत्यापित करें X-WC-Webhook-Signature कच्चे शरीर के बेस64 HMAC-SHA256 डाइजेस्ट के रूप में। एक सुरक्षित परीक्षण स्टोर में ऑर्डर या उत्पाद परिवर्तन को ट्रिगर करें, डिलीवरी का निरीक्षण करें और रिसीवर को तैनात किए बिना पुनरावृत्त करें।

WooCommerce क्या भेजता है और कब भेजता है

जब ऑर्डर, उत्पाद, कूपन या ग्राहक बनाए जाते हैं, अपडेट किए जाते हैं या हटाए जाते हैं तो WooCommerce एक डिलीवरी यूआरएल को सूचित कर सकता है। एक्सटेंशन विषय जोड़ सकते हैं, और डेवलपर कस्टम विषय परिभाषित कर सकते हैं। प्रत्येक कॉन्फ़िगर किए गए वेबहुक का एक नाम, स्थिति, विषय, डिलीवरी यूआरएल, रहस्य और एपीआई संस्करण होता है। आधिकारिक WooCommerce वेबहुक दस्तावेज़ीकरण निर्माण, विषय, वितरण लॉग और विफलता व्यवहार का वर्णन करता है।

एक वेबहुक किसी विषय से जुड़ा होता है, न कि प्रत्येक स्टोर म्यूटेशन से स्वचालित रूप से। आपके एकीकरण के लिए आवश्यक सबसे संकीर्ण विषय चुनें। ऑर्डर-निर्मित उपभोक्ता को प्रत्येक उत्पाद अद्यतन को भी संसाधित नहीं करना चाहिए। यह स्थानीय परीक्षण के दौरान व्यक्तिगत डेटा एक्सपोज़र, ट्रैफ़िक और आकस्मिक दुष्प्रभावों को कम करता है।

एक रॉ-बॉडी एक्सप्रेस एंडपॉइंट बनाएं

WooCommerce के हस्ताक्षर की गणना उसके द्वारा भेजे जाने वाले निकाय पर की जाती है। सत्यापन पूरा होने तक उन बाइट्स को सुरक्षित रखें। हस्ताक्षर हेडर में बेस64-एन्कोडेड बाइनरी 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 पार्सर से पहले चलना चाहिए। यदि मिडलवेयर पहले बॉडी को पार्स करता है, तो ऑब्जेक्ट को फिर से स्ट्रिंग करने से व्हाइटस्पेस या एस्केपिंग बदल सकता है और डाइजेस्ट अमान्य हो सकता है। यह वही रॉ-बॉडी नियम है जिसे इसमें शामिल किया गया है वेबहुक हस्ताक्षर मार्गदर्शिका, लेकिन WooCommerce विशेष रूप से Base64 आउटपुट का उपयोग करता है।

HTTPS सुरंग प्रारंभ करें

1. अपना रिसीवर चालू करें और पुष्टि करें कि वह सुन रहा है http://localhost:3000.
2. दौड़ना npx portpreview 3000 दूसरे टर्मिनल में.
3. सार्वजनिक HTTPS URL की प्रतिलिपि बनाएँ और जोड़ें /webhooks/woocommerce.
4. जब वर्डप्रेस अपनी प्रारंभिक पिंग और विषय डिलीवरी भेजता है तो प्रक्रिया को चालू रखें।

वर्डप्रेस होस्ट—वह ब्राउज़र नहीं जहां आपने wp-admin खोला था—सार्वजनिक URL तक पहुंचने में सक्षम होना चाहिए। एक सुरंग पुल जो सार्वजनिक आपकी निजी विकास प्रक्रिया के लिए अनुरोध करता है। यह विश्वसनीय टीएलएस भी प्रदान करता है, इसलिए आपको राउटर पोर्ट को उजागर करने या अपना स्वयं का सार्वजनिक प्रमाणपत्र स्थापित करने की आवश्यकता नहीं है।

WooCommerce में वेबहुक कॉन्फ़िगर करें

1. खुला WooCommerce → सेटिंग्स → उन्नत → वेबहुक.
2. चुनना वेबहुक जोड़ें और इसे एक पहचानने योग्य स्थानीय-विकास नाम दें।
3. चुनना सक्रिय स्थिति और एक विशिष्ट विषय, जैसे ऑर्डर बनाया गया।
4. पूर्ण टनल डिलीवरी यूआरएल चिपकाएँ।
5. एक लंबा यादृच्छिक रहस्य उत्पन्न करें और उसमें समान मान रखें WC_WEBHOOK_SECRET.
6. वेबहुक सहेजें, फिर विषय को परीक्षण स्टोर में ट्रिगर करें।

जब कोई सक्रिय वेबहुक पहली बार सहेजा जाता है, तो WooCommerce डिलीवरी URL पर एक पिंग भेजता है। पिंग कनेक्टिविटी की पुष्टि करता है लेकिन वास्तविक ऑर्डर पेलोड का विकल्प नहीं है। अपने समापन बिंदु को प्रारंभिक अनुरोध को सहन करने योग्य बनाएं और फिर चयनित विषय का अभ्यास करने के लिए परीक्षण डेटा बनाएं या अपडेट करें।

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

यदि आप बेस64 रहस्य को किसी पर्यावरण फ़ाइल में चिपकाते हैं, तो उसे उद्धृत करें ताकि विराम चिह्न संरक्षित रहे। रहस्य HMAC कुंजी है; WooCommerce REST API उपभोक्ता कुंजी और वर्डप्रेस पासवर्ड असंबंधित क्रेडेंशियल हैं।

डिलीवरी को रूट और ट्रेस करने के लिए हेडर का उपयोग करें

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 हो सकती है, इसलिए मल्टी-स्टोर एकीकरण के लिए एक कंपाउंड कुंजी की आवश्यकता होती है।

फ़ील्ड में बदलाव के लिए एक्सटेंशन की अपेक्षा करें

भुगतान, सदस्यता, कर, चेकआउट और पूर्ति एक्सटेंशन मेटाडेटा और लाइन-आइटम फ़ील्ड जोड़ सकते हैं। आपके व्यावसायिक तर्क के लिए आवश्यक फ़ील्ड को मान्य करें, अज्ञात फ़ील्ड को अनदेखा करें, और प्रतिगमन परीक्षणों के लिए एक स्कीमा संस्करण या न्यूनतम संशोधित स्थिरता सहेजें।

ईवेंट रसीद को पूर्ति से अलग करें

एक वेबहुक जो कहता है कि ऑर्डर बदला गया है उसे एक टिकाऊ कतार या इनबॉक्स में दर्ज करना चाहिए। इन्वेंटरी सिंक्रनाइज़ेशन, शिपिंग लेबल, ईआरपी कॉल और ग्राहक ईमेल पावती के बाद चलना चाहिए। यह धीमी निर्भरता को 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 → स्थिति → लॉग और आधिकारिक दस्तावेज़ में वर्णित वेबहुक डिलीवरी स्रोत के लिए फ़िल्टर करें। अपने स्थानीय टनल ट्रेस के साथ डिलीवरी यूआरएल, अनुरोध समय, प्रतिक्रिया स्थिति और प्रतिक्रिया निकाय की तुलना करें। प्रेषक लॉग उत्तर देता है कि क्या वर्डप्रेस ने अनुरोध का प्रयास किया था; रिसीवर लॉग उत्तर देता है कि आपके एप्लिकेशन ने इसके साथ क्या किया।

किसी असंपादित आदेश पेलोड को किसी सार्वजनिक निर्गम में कॉपी न करें। इसमें नाम, बिलिंग और शिपिंग पते, ईमेल, फोन, उत्पाद चयन और भुगतान मेटाडेटा शामिल हो सकते हैं। बग को पुन: उत्पन्न करने के लिए आवश्यक फ़ील्ड में फिक्स्चर को कम करें।

सामान्य WooCommerce वेबहुक विफलताओं का निवारण करें

वेबहुक अक्षम हो जाता है

लगातार पांच से अधिक डिलीवरी विफलताओं के बाद WooCommerce स्वचालित रूप से एक वेबहुक को अक्षम कर देता है। आधिकारिक गाइड के अनुसार 2xx, 301, या 302 के बाहर की प्रतिक्रियाओं को विफलताओं के रूप में गिना जाता है। समापन बिंदु को ठीक करें, वेबहुक को पुनः सक्रिय करें, और एक नियंत्रित परीक्षण भेजें। वैसे भी रीडायरेक्ट से बचें: वे हस्ताक्षर डिबगिंग को जटिल बनाते हैं और गलती से हस्ताक्षरित ग्राहक डेटा को किसी अनपेक्षित होस्ट को भेज सकते हैं।

हस्ताक्षर हमेशा अलग-अलग होते हैं

वेबहुक के कॉन्फ़िगर किए गए रहस्य के साथ सटीक रॉ बॉडी को हैश करें, बाइनरी एचएमएसी आउटपुट का अनुरोध करें, फिर इसे बेस 64-एनकोड करें। नोड में, वह है .digest('base64'). सामान्य गलतियाँ हैं हेक्स का उपयोग करना, REST API सीक्रेट का उपयोग करना, JSON को पहले पार्स करना, या अतिरिक्त न्यूलाइन बाइट्स शामिल करना।

प्रारंभिक पिंग काम करता है लेकिन ऑर्डर ईवेंट काम नहीं करता है

पुष्टि करें कि चयनित विषय आपके द्वारा ट्रिगर की गई कार्रवाई से मेल खाता है। एक ऑर्डर बनाना और मौजूदा ऑर्डर को बदलना अलग-अलग विषय हैं। सत्यापित करें कि स्थिति सक्रिय है, WooCommerce लॉग जांचें, और सुनिश्चित करें कि कोई प्लगइन या स्टेजिंग कैश अंतर्निहित हुक को नहीं रोक रहा है।

स्थानीय अनुरोध 404 लौटाते हैं

पूर्ण पथ, मार्ग विधि और सुरंग लक्ष्य पोर्ट की जाँच करें। वर्डप्रेस को पोस्ट करना होगा /webhooks/woocommerce, केवल सुरंग की उत्पत्ति नहीं। फ़्रेमवर्क मिडलवेयर को वेबहुक को किसी स्थानीयकृत या प्रमाणित पृष्ठ पर पुनर्निर्देशित नहीं करना चाहिए।

डिलीवरी का समय समाप्त

प्रमाणित घटना को जारी रखें और तुरंत 200 या 202 लौटाएँ। किसी कार्यकर्ता को दूरस्थ एपीआई कॉल और भारी परिवर्तन स्थानांतरित करें। जांचें कि क्या स्थानीय ब्रेकप्वाइंट अनुरोध को विफलता के रूप में वर्गीकृत करने के लिए पर्याप्त समय तक रोकते हैं।

पेलोड को दोबारा चलाने से 401 उत्पन्न होता है

कैप्चर किए गए अनुरोध में सटीक कच्चे बाइट्स और हस्ताक्षर हेडर को बरकरार रखा जाना चाहिए। JSON को संपादित करने से मूल हस्ताक्षर अमान्य हो जाता है। व्यवसाय-तर्क परीक्षणों के लिए, सत्यापन सीमा के बाद एक स्वच्छ उपकरण का उपयोग करें; एंड-टू-एंड परीक्षणों के लिए, एक समर्पित परीक्षण रहस्य के साथ एक नया HMAC तैयार करें। का पीछा करो सुरक्षित रीप्ले वर्कफ़्लो.

स्थानीय स्टोर डेटा के लिए सुरक्षा चेकलिस्ट

• जब भी संभव हो सिंथेटिक ग्राहकों और उत्पादों के साथ स्टेजिंग स्टोर पर परीक्षण करें।
• स्थानीय विकास के लिए एक अद्वितीय वेबहुक रहस्य का उपयोग करें और एक्सपोज़र के बाद इसे घुमाएँ।
• मुख्य भाग को पार्स करने, लॉग करने या पंक्तिबद्ध करने से पहले हस्ताक्षर सत्यापित करें।
• क्रिप्टोग्राफ़िक सत्यापन के बाद अपेक्षित स्टोर स्रोत और विषय की अनुमति सूची।
• कैप्चर से पते, संपर्क विवरण, ऑर्डर नोट्स और भुगतान मेटाडेटा को संशोधित करें।
• कभी भी टीएलएस सत्यापन को अक्षम न करें या रिसीवर के सामने wp-एडमिन क्रेडेंशियल उजागर न करें।

स्थानीय आर्किटेक्चर को उत्पादन से मेल खाना चाहिए: HTTPS ट्रांसपोर्ट, रॉ-बॉडी प्रमाणीकरण, टिकाऊ स्वीकृति, निष्क्रिय प्रसंस्करण, तेज़ प्रतिक्रिया और श्रव्य विफलताएं। भिन्न HMAC हेडर वाले किसी अन्य वाणिज्य प्रदाता के लिए, तुलना करें शॉपिफाई स्थानीय वेबहुक गाइड.