स्थानीय स्तर पर पोलर वेबहुक का परीक्षण करने के लिए, अपना वेबहुक हैंडलर चलाएं, पोलर सीएलआई स्थापित करें और प्रमाणित करें, फिर उपयोग करें polar listen http://localhost:3000/api/webhooks/polar हस्ताक्षरित घटनाओं को सीधे अपनी मशीन पर रिले करने के लिए। श्रोता द्वारा मुद्रित अस्थायी रहस्य को इसमें कॉपी करें POLAR_WEBHOOK_SECRET, इसे संसाधित करने से पहले कच्चे शरीर को सत्यापित करें, और एक सैंडबॉक्स चेकआउट, ऑर्डर, धनवापसी, या सदस्यता ईवेंट ट्रिगर करें।
पोलर सीएलआई सबसे सरल स्थानीय वर्कफ़्लो क्यों है?
एक सामान्य उत्पादन वेबहुक एंडपॉइंट HTTPS पर सार्वजनिक रूप से पहुंच योग्य होना चाहिए। पोलर एक उद्देश्य-निर्मित स्थानीय श्रोता प्रदान करता है, इसलिए आपको एक स्थायी समापन बिंदु बनाने या बार-बार अस्थायी कॉलबैक यूआरएल को डैशबोर्ड में पेस्ट करने की आवश्यकता नहीं है। सीएलआई आपके संगठन से जुड़ता है, एक सत्र हस्ताक्षर रहस्य प्रदर्शित करता है, ईवेंट प्राप्त करता है, और उन्हें आपके द्वारा प्रदान किए गए स्थानीय यूआरएल पर अग्रेषित करता है।
पोलर का अधिकारी स्थानीय वेबहुक दस्तावेज़ीकरण उपयोग करता है polar listen http://localhost:3000/. जब आपका एप्लिकेशन किसी रूट के नीचे वेबहुक को संभालता है तो इसे पूर्ण पथ पर इंगित करें /api/webhooks/polar. यह उत्पादन से पहले पथ की गलतियों को पकड़ता है और वही एप्लिकेशन हैंडलर रखता है जिसे आप तैनात करना चाहते हैं।
सीएलआई स्थापित करें और सुनना शुरू करें
- अपना एप्लिकेशन प्रारंभ करें और पुष्टि करें कि इसका POST मार्ग स्थानीय रूप से उपलब्ध है।
- आधिकारिक दस्तावेज़ से कमांड का उपयोग करके पोलर सीएलआई स्थापित करें।
- भागो
polar loginऔर सही खाते को अधिकृत करें. - प्रारंभ करें
polar listen http://localhost:3000/api/webhooks/polar. - उस संगठन का चयन करें जिसके पास आपके सैंडबॉक्स उत्पाद हैं।
- प्रदर्शित सत्र रहस्य को इसमें कॉपी करें
POLAR_WEBHOOK_SECRETऔर अपने ऐप को पुनः आरंभ करें यदि इसका वातावरण केवल स्टार्टअप पर लोड किया गया है। - सैंडबॉक्स कार्रवाई ट्रिगर करें और अपने स्थानीय लॉग के साथ सीएलआई डिलीवरी स्थिति की तुलना करें।
श्रोता रहस्य स्थानीय सत्र का हिस्सा है। यह न मानें कि यह डैशबोर्ड एंडपॉइंट रहस्य के बराबर है या उत्पादन मूल्य का पुन: उपयोग न करें। यदि आप पुनः कनेक्ट होते हैं और एक अलग रहस्य प्राप्त करते हैं, तो दोबारा परीक्षण करने से पहले स्थानीय वातावरण को अपडेट करें।
Next.js ऐप राउटर हैंडलर बनाएं
पोलर मानक वेबहुक विनिर्देश का अनुसरण करता है। एक डिलीवरी शामिल है webhook-id, webhook-timestamp, और webhook-signature. सत्यापन को सटीक कच्चे अनुरोध निकाय का उपयोग करना चाहिए; बुला रहा हूँ request.json() पहले और ऑब्जेक्ट को फिर से क्रमबद्ध करने से हस्ताक्षरित बाइट्स बदल सकते हैं।
// app/api/webhooks/polar/route.ts
import { Webhook } from 'standardwebhooks';
export const runtime = 'nodejs';
export async function POST(request: Request) {
const rawBody = await request.text();
const secret = process.env.POLAR_WEBHOOK_SECRET;
if (!secret) {
return new Response('Webhook secret is not configured', { status: 500 });
}
const headers = {
'webhook-id': request.headers.get('webhook-id') ?? '',
'webhook-timestamp': request.headers.get('webhook-timestamp') ?? '',
'webhook-signature': request.headers.get('webhook-signature') ?? '',
};
try {
const encodedSecret = Buffer.from(secret.trim(), 'utf8').toString('base64');
const payload = new Webhook(encodedSecret).verify(rawBody, headers);
await acceptPolarEvent(headers['webhook-id'], payload);
return Response.json({ received: true });
} catch {
return new Response('Invalid signature', { status: 403 });
}
}ध्रुवीय का वितरण दस्तावेज एक सामान्य कस्टम-सत्यापन जाल का आह्वान करता है: मानक वेबहुक लाइब्रेरीज़ बेस 64-एन्कोडेड रहस्य की अपेक्षा करती हैं, जबकि पोलर एक सामान्य गुप्त स्ट्रिंग प्रदान करता है। पोलर एसडीके सहायक इस रूपांतरण को स्वचालित रूप से संभालते हैं। उपयोग करते समय standardwebhooks जैसा कि ऊपर दिखाया गया है, सीधे बेस64 संपूर्ण ध्रुवीय रहस्य को एनकोड करता है।
उपलब्ध होने पर आधिकारिक फ्रेमवर्क एडॉप्टर को प्राथमिकता दें
पोलर ऐसे एडेप्टर प्रकाशित करता है जो हस्ताक्षर सत्यापन को टाइप किए गए पेलोड हैंडलर के साथ जोड़ते हैं। अधिकारी एक्सप्रेस एडॉप्टर दस्तावेज़ीकरण चेकआउट, ऑर्डर, रिफंड, लाभ और सदस्यता घटनाओं के लिए विस्तृत कॉलबैक प्रदान करता है। एक एडाप्टर हेडर पार्सिंग या गुप्त एन्कोडिंग को गलत तरीके से लागू करने की संभावना को कम कर देता है।
import express from 'express';
import { Webhooks } from '@polar-sh/express';
const app = express();
app.use(express.json());
app.post('/webhooks/polar', Webhooks({
webhookSecret: process.env.POLAR_WEBHOOK_SECRET,
onOrderPaid: async (event) => {
await queueOrderPaid(event.data);
},
onSubscriptionActive: async (event) => {
await queueSubscriptionActive(event.data);
},
}));
app.listen(3000);आपके द्वारा इंस्टॉल किए गए संस्करण के लिए एडॉप्टर के दस्तावेज़ीकृत मिडलवेयर ऑर्डर का पालन करें। यदि आप इसके बजाय एक सामान्य सत्यापनकर्ता का उपयोग करते हैं, तो कच्चे शरीर को स्पष्ट रूप से संरक्षित करें। स्ट्रीम को पढ़ने वाले एडॉप्टर को उस मिडलवेयर के साथ न मिलाएं जो पहले इसका उपभोग करता है।
आपको किन ध्रुवीय घटनाओं का परीक्षण करना चाहिए?
चेकआउट इवेंट
चेकआउट इवेंट किसी सत्र को भुगतान ऑर्डर बनने से पहले ट्रैक करने में मदद करते हैं। केवल इसलिए कि चेकआउट बनाया गया था, पहुंच प्रदान किए बिना सफल समापन और परित्यक्त या अद्यतन स्थितियों का परीक्षण करें। भुगतान किया गया ऑर्डर या सक्रिय सदस्यता आधिकारिक पात्रता संकेत बनी रहनी चाहिए।
ऑर्डर का भुगतान कर दिया गया और वापस कर दिया गया
ऑर्डर-पेड इवेंट के लिए, पोलर ग्राहक और उत्पाद को अपने आंतरिक खाते में मैप करें, फिर खरीदे गए लाभ को ठीक एक बार प्रदान करें। आपकी धनवापसी नीति के अनुसार धनवापसी घटनाओं को केवल प्रभावित पात्रता को उलट देना चाहिए। स्टोर प्रदाता आईडी ताकि समर्थन पोलर के साथ घटना का समाधान कर सके।
सदस्यता जीवनचक्र घटनाएँ
निर्माण, सक्रियण, अपडेट, रद्दीकरण, निरस्तीकरण और आपके उत्पाद द्वारा समर्थित किसी भी पूर्व-देय व्यवहार का परीक्षण करें। रद्दीकरण अनुरोध का मतलब यह नहीं हो सकता कि पहुंच तुरंत समाप्त हो जाएगी। जीवनचक्र को एक तक कम करने के बजाय स्थिति और प्रभावी तिथियों को संग्रहीत करें is_active झंडा.
लाभ अनुदान
यदि आपका एकीकरण पोलर लाभों का उपयोग करता है, तो बिलिंग घटनाओं से स्वतंत्र रूप से अनुदान निर्माण, अद्यतन और निरस्तीकरण का परीक्षण करें। हैंडलर्स को वांछित स्थिति में एकत्रित करें ताकि एक ही अनुदान दो बार प्राप्त करने से डुप्लिकेट संसाधनों का प्रावधान न हो।
हर आयोजन को निरर्थक बनाएं
नेटवर्क डिलीवरी बिल्कुल एक बार होने वाला लेनदेन नहीं है। एक हैंडलर अपना डेटाबेस कार्य कर सकता है और प्रतिक्रिया खो सकता है, जिससे प्रेषक को पुनः प्रयास करना पड़ सकता है। उपयोग करें webhook-id एक अद्वितीय डिलीवरी कुंजी के रूप में और उसी लेनदेन में इसका दावा करें जो आपके आवेदन की स्थिति को अपडेट करता है।
await db.transaction(async (tx) => {
const firstDelivery = await tx.webhookReceipts.insertIfAbsent({
provider: 'polar',
deliveryId: webhookId,
});
if (!firstDelivery) return;
await applyPolarEvent(tx, payload);
await tx.outbox.enqueue('polar-event-accepted', { webhookId });
});पहले से ही पूर्ण हो चुके डुप्लिकेट के लिए 2xx प्रतिक्रिया लौटाएँ। केवल ग्राहक या सदस्यता आईडी के आधार पर डुप्लिकेट न काटें क्योंकि कई वैध ईवेंट एक ही संसाधन को लक्षित करते हैं। द वेबहुक पुनः प्रयास और निष्क्रियता मार्गदर्शिका इनबॉक्स और आउटबॉक्स पैटर्न को अधिक विस्तार से कवर करता है।
पावती कार्य छोटा रखें
अनुरोध को सत्यापित करें, इसे जारी रखें या एक टिकाऊ नौकरी सूचीबद्ध करें, और सफलता लौटाएँ। ईमेल, लाइसेंस जनरेशन, रिपॉजिटरी एक्सेस, एनालिटिक्स और थर्ड-पार्टी एपीआई कॉल एसिंक्रोनस रूप से चलने चाहिए। तेज़ पावती पुनर्प्रयास को कम करती है जबकि एक टिकाऊ लेखन घटनाओं को गायब होने से रोकता है यदि प्रक्रिया लौटने के बाद बाहर निकल जाती है।
अज्ञात घटना प्रकारों को वैध हस्ताक्षर सत्यापन के बाद दर्ज और स्वीकार किया जाना चाहिए। पोलर समय के साथ घटना प्रकार जोड़ सकता है; प्रत्येक अपरिचित मान को फेंकने से एक हानिरहित स्कीमा जोड़ बार-बार वितरण विफलताओं में परिवर्तित हो जाता है।
पोलर वेबहुक लोकलहोस्ट विफलताओं का निवारण करें
सीएलआई कनेक्ट होता है लेकिन रूट 404 लौटाता है
के लिए पूरा स्थानीय मार्ग पार करें polar listen, न केवल बंदरगाह. Next.js ऐप राउटर में, सुनिश्चित करें कि फ़ाइल का नाम है route.ts और निर्यात POST. 404 लौटाने वाला ब्राउज़र GET यह साबित नहीं करता है कि POST रूट गायब है, इसलिए इसके साथ परीक्षण करें curl -X POST.
प्रत्येक अनुरोध 403 लौटाता है
पुष्टि करें कि ऐप ने वर्तमान सीएलआई सत्र द्वारा मुद्रित रहस्य को लोड किया है। रॉ बॉडी और सभी तीन मानक वेबहुक हेडर को सुरक्षित रखें। यदि आप सामान्य लाइब्रेरी का उपयोग करते हैं, तो बेस64 पोलर सीक्रेट को ठीक एक बार एनकोड करता है; यदि आप पोलर एसडीके हेल्पर का उपयोग करते हैं, तो मूल रहस्य पास करें और एसडीके को एन्कोडिंग संभालने दें।
चेकआउट के बाद कोई ईवेंट प्रकट नहीं होता है
सत्यापित करें कि सीएलआई उसी संगठन और परिवेश से जुड़ा है जहां कार्रवाई हुई थी। श्रोता टर्मिनल को खुला रखें, सैंडबॉक्स संसाधनों का उपयोग करें, और पुष्टि करें कि आपकी कार्रवाई वास्तव में उस ईवेंट स्थिति तक पहुंचती है जिसकी आपने सदस्यता ली है।
इवेंट दो बार संसाधित होते हैं
के लिए एक अद्वितीय बाधा जोड़ें webhook-id और डुप्लिकेट के लिए सफलता लौटाएँ। जांचें कि क्या आपके राज्य के अपडेट के बाद लेकिन प्रतिक्रिया से पहले कोई अपवाद होता है। धीमे दुष्प्रभावों को आउटबॉक्स-समर्थित कार्यकर्ता में ले जाएं।
पुराना कैप्चर किया गया अनुरोध सत्यापन में विफल रहता है
मानक वेबहुक सत्यापन में रीप्ले हमलों को सीमित करने के लिए एक टाइमस्टैम्प शामिल है। एक पुराना कैप्चर सामान्य सत्यापन विंडो में विफल होना चाहिए। व्यवसाय-तर्क परीक्षणों के लिए, एक बार ताज़ा डिलीवरी को सत्यापित करें और प्रमाणीकरण सीमा के पीछे एक स्वच्छ पेलोड फिक्स्चर को सहेजें।
उत्पादन से पहले सुरक्षा जांच सूची
- अलग-अलग स्थानीय, सैंडबॉक्स और उत्पादन समापन बिंदु रहस्यों का उपयोग करें।
- प्रसंस्करण से पहले रॉ बॉडी, टाइमस्टैम्प, डिलीवरी आईडी और हस्ताक्षर सत्यापित करें।
- एपीआई टोकन और वेबहुक रहस्यों को केवल सर्वर वातावरण चर में रखें।
- द्वारा डुप्लिकेट करें
webhook-idऔर उत्पाद, संगठन और ग्राहक पहचानकर्ताओं को मान्य करें। - साझा लॉग से ग्राहक ईमेल, बिलिंग डेटा, मेटाडेटा और पूर्ण पेलोड को संशोधित करें।
- अनुरोध-आकार सीमा लागू करें और बार-बार अमान्य हस्ताक्षरों की निगरानी करें।
- स्थानीय श्रोता को एक स्थिर HTTPS एंडपॉइंट से बदलें और लाइव उत्पादों को सक्षम करने से पहले एक ताज़ा सैंडबॉक्स प्रवाह का परीक्षण करें।
पोलर सीएलआई परिनियोजन लूप को हटा देता है, लेकिन इसे उत्पादन नियंत्रण को नहीं हटाना चाहिए। हस्ताक्षर सत्यापन, निष्क्रियता, ईवेंट फ़िल्टरिंग और टिकाऊ प्रसंस्करण को स्थानीय रूप से सक्षम रखें ताकि आपके द्वारा परीक्षण किया जाने वाला कोड वही कोड हो जिसे आप शिप करते हैं। फ़्रेमवर्क-स्वतंत्र सत्यापन विवरण के लिए, पढ़ें वेबहुक हस्ताक्षर सत्यापन मार्गदर्शिका और सामान्य स्थानीय डिबगिंग वर्कफ़्लो.