लोकलहोस्ट पर लेमन स्क्वीजी वेबहुक्स का परीक्षण करने के लिए, अपनी ऐप शुरू करें, इसके वेबहुक रूट को एक सार्वजनिक HTTPS टनल के साथ एक्सपोज़ करें, सेटिंग्स → वेबहुक्स में एक टेस्ट मोड वेबहुक बनाएँ, और रॉ रिक्वेस्ट बॉडी को सत्यापित करें X-Signature सिरमाला। वास्तविक ऑर्डर डेटा के लिए एक टेस्ट चेकआउट का उपयोग करें और ऐसे जीवनचक्र इवेंट्स के लिए Lemon Squeezy के सब्सक्रिप्शन सिमुलेशन नियंत्रण का उपयोग करें जिनका इंतजार करना मुश्किल हो।
सही स्थानीय सेटअप कैसा दिखता है
लेमन स्क्वीज़ी एक HTTP भेजता है POST इसके बुनियादी ढांचे से, इसलिए यह पहुँच नहीं सकता localhost आपके कंप्यूटर पर। टनल सार्वजनिक TLS को समाप्त करता है और अपरिवर्तित मेथड, बॉडी, और हेडर को किसी स्थानीय मार्ग जैसे को फॉरवर्ड करता है http://localhost:3000/api/webhooks/lemonsqueezy.
एक पूर्ण परीक्षण में चार भाग होते हैं: लेमन स्क्वीज़ी टेस्ट मोड, एक सार्वजनिक कॉलबैक URL, डैशबोर्ड और स्थानीय वातावरण में एक ही साइनिंग सीक्रेट, और एक हैंडलर जो सदस्यता या लाइसेंस स्थिति बदलने से पहले सत्यापित करता है। यह कॉपी किए गए JSON को पोस्ट करने से अधिक उपयोगी है। curl, क्योंकि एक असली डिलीवरी दोनों रूटिंग और प्रदाता-जनित साइनचर का परीक्षण करती है।
वेबहुक बनाएं और एक परीक्षण ईवेंट भेजें
- अपने ऐप को पोर्ट 3000 पर चलाएँ और सत्यापित करें कि रूट स्वीकार करता है
POST. - टनेल शुरू करें
npx portpreview 3000. - लेमन स्क्वीजी डैशबोर्ड को टेस्ट मोड में स्विच करें।
- सेटिंग्स खोलें → वेबहुक्स और जोड़ें
https://your-subdomain.portpreview.dev/api/webhooks/lemonsqueezy. - एक मजबूत यादृच्छिक साइनिंग सीक्रेट उत्पन्न करें, इसे के रूप में सहेजें
LEMONSQUEEZY_WEBHOOK_SECRETऔर केवल उन घटनाओं का चयन करें जिन्हें आपका एप्लिकेशन उपयोग करता है। - एक परीक्षण खरीदारी बनाएं या उपलब्ध परीक्षण मोड सदस्यता सिमुलेशन क्रिया का उपयोग करें, फिर वितरण लॉग और आपकी स्थानीय प्रतिक्रिया की जाँच करें।
अधिकारिक लेमन स्क़्वीज़ी वेबहुक प्रलेखन यह आपको हाल की पेलोड की जाँच करने और सेटिंग्स पृष्ठ से रिकॉर्ड किए गए वेबहुक को पुन: भेजने की अनुमति देता है। पुन: भेजना रिग्रेशन परीक्षण के लिए मूल्यवान है, लेकिन आपका एप्लिकेशन इसे दूसरे व्यवसायिक ईवेंट के बजाय एक डुप्लिकेट के रूप में मानना चाहिए।
सत्यापित करें X-Signature JSON पार्स करने से पहले
लेमन स्क्वीजी साइनिंग सीक्रेट का उपयोग करके अनुरोध पेलोड पर एक HMAC-SHA256 डाइजेस्ट की गणना करता है और हेक्साडेसिमल डाइजेस्ट भेजता है X-Signature. सटीक कच्चे बॉडी बाइट्स पर डाइजेस्ट की गणना करें और एक स्थिर-समय फ़ंक्शन के साथ समान लंबाई वाले बफ़रों की तुलना करें। प्राथमिक अनुरोधों पर हस्ताक्षर करने का दस्तावेज़ीकरण इसमें Node, PHP, Python, और Ruby के लिए उदाहरण शामिल हैं।
// app/api/webhooks/lemonsqueezy/route.ts
import crypto from 'node:crypto';
import { NextRequest, NextResponse } from 'next/server';
export async function POST(request: NextRequest) {
const secret = process.env.LEMONSQUEEZY_WEBHOOK_SECRET;
if (!secret) return new NextResponse('server misconfigured', { status: 500 });
const rawBody = await request.text();
const suppliedHex = request.headers.get('x-signature') ?? '';
if (!/^[0-9a-f]{64}$/i.test(suppliedHex)) {
return new NextResponse('invalid signature', { status: 401 });
}
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest();
const supplied = Buffer.from(suppliedHex, 'hex');
if (supplied.length !== expected.length ||
!crypto.timingSafeEqual(supplied, expected)) {
return new NextResponse('invalid signature', { status: 401 });
}
const event = JSON.parse(rawBody);
await acceptEvent(event);
return NextResponse.json({ received: true });
}फोन न करें request.json() पहले। प्राप्त वस्तु का पुनः सीरियलाइज़ेशन मामूली दिखने वाले बाइट्स को बदल सकता है और HMAC को तोड़ सकता है। लंबाई की जांच भी आवश्यक है क्योंकि Node का timingSafeEqual जब बफर की लंबाई भिन्न होती है तो थ्रो करता है। लेमन स्क्वीजी का आधिकारिक Next.js वेबहुक ट्यूटोरियल उसी कच्चे-दिलारी अनुक्रम का पालन करता है।
अपना डेटाबेस अपडेट करने से पहले पेलोड को समझें
बॉडी एक JSON:API संसाधन वस्तु है। meta.event_name घटना की पहचान करता है, meta.custom_data चेकआउट के माध्यम से पारित डेटा को ले जाता है, और data में आदेश, सदस्यता, या लाइसेंस-कुंजी संसाधन शामिल हैं। लेमन स्क्वीजी भी भेजता है X-Event-Name; हस्ताक्षरित बॉडी को प्राधिकृत इनपुट के रूप में मानें और रूटिंग डायग्नोस्टिक्स के लिए हेडर का उपयोग करें।
आदेश और ग्राहक पहचान
के लिए order_created, खरीदारी को चेकआउट कस्टम डेटा में सर्वर-जनरेटेड पहचानकर्ता का उपयोग करके आंतरिक उपयोगकर्ता से मैप करें। बिना स्वामित्व की जाँच किए ग्राहक-प्रदान किया गया उपयोगकर्ता आईडी पर भरोसा न करें। बाद में सब्सक्रिप्शन या रिफंड इवेंट्स की सुलह के लिए लेमन स्क़्वीजी के संसाधन आईडी और वेरिएंट आईडी को सुरक्षित रखें।
सब्सक्रिप्शन एक स्टेट मशीन हैं
हैंडल subscription_created, subscription_updated, subscription_cancelled, subscription_resumed, और subscription_expired अलग-अलग ट्रांज़िशन के रूप में। रद्द करना इसका मतलब हो सकता है कि पहुंच बिलिंग-पिरियड के अंत तक मान्य बनी रहती है; समाप्ति यह मजबूत संकेत है कि सदस्यता अंत हो गई है। एक बूलियन को टॉगल करने के बजाय तारीखों और स्थिति को मॉडल करें।
भुगतान विफलताएं और वसूली
परीक्षण विफल हुआ और नवीकरण प्रवाह को पुनर्प्राप्त किया गया जहां परीक्षण मोड उनका समर्थन करता है। एक असफल भुगतान तुरंत पहुंच रद्द नहीं करना चाहिए; अपने उत्पाद नीति द्वारा परिभाषित ग्रेस पीरियड लागू करें और बाद के भुगतान या सब्सक्रिप्शन घटनाओं को खाते को नवीनतम प्रदाता स्थिति में लाने दें।
पुनः प्रयासों के लिए अपरिवर्तनीय (आदत्त) प्रसंस्करण की आवश्यकता होती है
लेमन स्क्वीजी के अनुसार वेबहुक अनुरोध संदर्भ, एक 200 प्रतिक्रिया मार्क्स को सफल के रूप में दर्ज किया जाता है। अन्य स्थिति को अधिकतम तीन बार तक फिर से प्रयास किया जाता है, जिसमें प्रत्यावर्ती देरी लगभग 5, 25, और 125 सेकंड के रूप में दिखाई जाती है। डैशबोर्ड फिर से भेजने से एक ही तार्किक घटना कई बार आ सकती है।
स्थिर साइन किए गए पेलोड फ़ील्ड से एक आइडेम्पोटेंसी कुंजी बनाएं। एक व्यावहारिक दृष्टिकोण है वेबहुक के संसाधन आईडी, ईवेंट नाम और ईवेंट टाइमस्टैम्प के लिए एक अद्वितीय डेटाबेस रो, या जब कोई विशेष ईवेंट आईडी मौजूद न हो तो कच्चे साइन किए गए बॉडी का हैश। उस रसीद को डालें और एक ही लेनदेन में एप्लिकेशन स्टेट को अपडेट करें। लौटाएँ। 200 पहले से पूरे किए गए डुप्लिकेट के लिए।
BEGIN;
INSERT INTO webhook_receipts (fingerprint, received_at)
VALUES ($1, now())
ON CONFLICT DO NOTHING;
-- Continue only if one row was inserted.
UPDATE subscriptions SET provider_status = $2 WHERE provider_id = $3;
COMMIT;ईमेल डिलीवरी या धीमी तृतीय-पक्ष API कॉल को स्वीकृति पथ का हिस्सा न बनाएं। एक ही लेनदेन में एक जॉब संग्रहित करें, उत्तर दें, और अंतःप्रभावों को संभालने के लिए एक वर्कर को छोड़ दें। व्यापक वेबहुक पुनः प्रयास और अद्वितीयता गाइड इस पैटर्न को कवर करता है।
लिमोन स्कूजी वेबहुक लोकलहोस्ट परीक्षणों की समस्या निवारण
कोई भी अनुरोध ऐप तक नहीं पहुँचता
जाँच करें कि सुरंग अभी भी चल रही है, कॉलबैक में रूट उपसर्ग शामिल है, और आपके फ्रेमवर्क में उसी सटीक पथ पर एक POST हैंडलर है। सार्वजनिक एंडपॉइंट को स्वयं कॉल करें। एक सुरंग 502 स्थानीय पोर्ट की ओर इशारा करता है; एक फ्रेमवर्क 404 रूट प्लेसमेंट की ओर इशारा करता है।
हर हस्ताक्षर अमान्य है
पुष्टि करें कि टेस्ट मोड और लाइव मोड अलग वेबहुक रिकॉर्ड या सीक्रेट का उपयोग नहीं कर रहे हैं। बॉडी को एक बार टेक्स्ट या बाइट्स के रूप में पढ़ें, न तो बॉडी और न ही सीक्रेट को ट्रिम करें, और सुनिश्चित करें कि ग्लोबल JSON मिडलवेयर पहले न चले। जांचें कि क्या X-Signature पहुंच गया, लेकिन कभी भी साइनिंग सीक्रेट को प्रिंट न करें।
डिलीवरी बार-बार पुनः प्रयास कर रही है
लेमन स्क्वीज़ी उम्मीद करता है 200लॉगिन पेज पर रीडायरेक्ट नहीं। वेबहुक पाथ को CSRF और यूजर-सत्र मिडलवेयर से बाहर रखें जबकि सिग्नेचर वेरिफिकेशन बनाए रखें। डेटाबेस त्रुटियों को पकड़ें, काम छोटा रखें, और यह सुनिश्चित करें कि हर हैंडल किए गए इवेंट ब्रांच पर वास्तव में एक सफलता प्रतिक्रिया वापस की जाए।
सब्सक्रिप्शन सिमुलेशन अनुपलब्ध है
सिमुलेशन नियंत्रणों के लिए उपयुक्त टेस्ट मोड सदस्यता डेटा की आवश्यकता होती है। कुछ भुगतान सिमुलेशनों के लिए नवीनीकरण इतिहास की आवश्यकता होती है। आवश्यक टेस्ट सदस्यता या टेस्ट खरीद पहले बनाएं, फिर लेमन स्क्वीजी के वर्णित सदस्यता क्रिया मेनू का उपयोग करें। वेबहुक डेवलपर गाइड.
सुरक्षा और लाइव जाने की चेकलिस्ट
- एक रैंडम साइनिंग सीक्रेट उत्पन्न करें, इसे पर्यावरण कॉन्फ़िगरेशन में स्टोर करें, और यदि यह उजागर हो जाए तो इसे बदल दें।
- JSON पार्सिंग, डेटाबेस लेखन, लाइसेंस जेनरेशन, या एक्सेस बदलाव से पहले कच्चे बॉडी पर HMAC सत्यापित करें।
- टाइमिंग-सेफ तुलना का उपयोग करें और गायब या खराब हस्ताक्षरों को अस्वीकार करें।
- टेस्ट मोड और लाइव वेबहूक रहस्यों और रिकॉर्ड्स को अलग रखें।
- केवल POST की अनुमति दें, एक उचित बॉडी-साइज़ सीमा लागू करें, अवैध अनुरोधों पर दर-सीमा लगाएँ, और लॉग से ग्राहक डेटा को छिपाएँ।
- टेस्ट डुप्लीकेट्स, आऊट-ऑफ-ऑर्डर लाइफसायकल इवेंट्स, डेटाबेस डाउनटाइम, और टाइमआउट रिकवरी से पहले अपने प्रोडक्शन URL के साथ टनल को बदलें।
एक सफल सामान्य-मार्ग चेकआउट केवल यह सिद्ध करता है कि एक घटना पहुँचाई गई। एक उत्पादन-तैयार इंटीग्रेशन हस्ताक्षर अस्वीकार, पुनरावृत्ति सुरक्षा, जीवनचक्र समाकलन, और गैर-200 प्रतिक्रिया से पुनर्प्राप्ति को सिद्ध करता है। अंतर्निहित क्रिप्टोग्राफिक समस्याओं के लिए, देखें हस्ताक्षर सत्यापन गाइड.