401 या 403 लौटाने वाला वेबहुक कुछ ही श्रेणियों में आता है। ज़्यादातर बार यह सिग्नेचर की समस्या भी नहीं होती — यह कोई middleware या फ़्रेमवर्क डिफ़ॉल्ट है जो आपके कोड के चलने से पहले अनुरोध को अस्वीकार कर देता है। यह वही नैदानिक checklist है जिसका हम उपयोग करते हैं, उसी क्रम में जिसमें इस्तेमाल करते हैं।
पहले, 401 को 403 से अलग करें
इनका मतलब अलग है और ठीक करने का तरीक़ा भी अलग।
401 Unauthorized: सर्वर ने अनुरोध पाया, credential (या सिग्नेचर) देखा, और स्वीकार नहीं किया। आपका handler शायद चला, एक अपेक्षित सिग्नेचर गणना की, और अस्वीकार किया।
403 Forbidden: सर्वर ने अनुरोध पाया और किसी अन्य कारण से प्रोसेस करने से इनकार किया। अक्सर अनुरोध आपके handler तक पहुँचा ही नहीं — किसी middleware या फ़्रेमवर्क डिफ़ॉल्ट ने 403 भेजा।
अपने tunnel की अनुरोध कैप्चर खोलें और response देखें। यदि आपको अपने handler का response body ("invalid signature") दिखता है, तो यह आपके कोड से 401 है। यदि response सामान्य है और आपके handler के log कुछ नहीं दिखाते, तो handler चलने से पहले फ़्रेमवर्क ने अस्वीकार किया।
पाँच सबसे संभावित कारण
1. CSRF middleware (Django, Rails, Laravel)
डिफ़ॉल्ट CSRF सुरक्षा session token रहित POST को अस्वीकार करती है। वेबहुक प्रदाता ऐसा नहीं भेजते। लक्षण: 403, सामान्य response body, कोई handler log नहीं।
ठीक करें: वेबहुक route को CSRF सुरक्षा से बाहर रखें। Django में @csrf_exempt। Rails में skip_before_action :verify_authenticity_token, only: [:webhook]। Laravel में path को VerifyCsrfToken::$except में जोड़ें। Django वेबहुक गाइड Django संस्करण को शुरू से अंत तक समझाती है।
2. auth middleware बहुत व्यापक रूप से लागू
आपने auth middleware को वैश्विक रूप से जोड़ा (JWT, session जाँच, API key आवश्यकता) और वेबहुक route ने इसे विरासत में लिया। प्रदाता आपका auth हेडर नहीं भेजता, इसलिए middleware handler चलने से पहले 401 भेजता है।
ठीक करें: वेबहुक path को अपने auth middleware से बाहर रखें। वेबहुक प्रमाणीकरण सिग्नेचर है, वह स्कीम नहीं जो आपके बाक़ी API की रक्षा करती है।
3. सिग्नेचर सत्यापन विफल
आपका handler चला, एक अपेक्षित सिग्नेचर गणना की, और मेल नहीं खाया। आवृत्ति के लगभग घटते क्रम में पाँच उप-कारण:
- सत्यापन चलने से पहले body को middleware ने पार्स किया (कच्चा body चला गया)।
- ग़लत एन्कोडिंग (hex vs base64)। देखें सिग्नेचर सत्यापन गाइड।
- ग़लत secret (test vs live, dashboard vs CLI, env फ़ाइल vs runtime)।
- timestamp बहुत पुराना (सिग्नेचर मान्य पर बासी — शायद आप पुराने रीप्ले किए payload से टेस्ट कर रहे हैं)।
- env फ़ाइल से लोड किए secret के अंत में whitespace।
4. ग़लत tunnel URL रजिस्टर किया
आपने tunnel रीस्टार्ट किया और URL बदल गया, पर प्रदाता dashboard में अब भी पुराना है। लक्षण 401 जैसा दिखता है क्योंकि अनुरोध आप तक पहुँचा ही नहीं — पर असल में एक अलग अनुरोध एक अलग सर्वर तक पहुँच रहा है (अक्सर पिछला tunnel सत्र, जो अब इनकार करता या 401 लौटाता है)।
ठीक करें: पुष्टि करें कि प्रदाता dashboard का URL आपके वर्तमान tunnel सत्र से मेल खाता है। स्थिर URL चाहिए तो नामित tunnel या आरक्षित subdomain देखें।
5. CORS, content-type या method प्रतिबंध
वेबहुक के लिए कम सामान्य पर संभव। यदि आपका route केवल application/json स्वीकार करता है और प्रदाता application/x-www-form-urlencoded भेजता है (जैसे Twilio), कुछ फ़्रेमवर्क 415 देते हैं — पर ग़लत कॉन्फ़िगर किया 403 दे सकता है। या आपका route GET के लिए रजिस्टर है और प्रदाता POST करता है।
90-सेकंड का नैदानिक प्रवाह
यह वह क्रम है जिससे हम गुज़रते हैं:
- response body पढ़ें। यदि इसमें आपके handler के शब्द हैं, अनुरोध handler तक पहुँचा। सिग्नेचर डीबगिंग की ओर बढ़ें। यदि यह सामान्य फ़्रेमवर्क त्रुटि पृष्ठ है, अनुरोध नहीं पहुँचा। middleware डीबगिंग की ओर बढ़ें।
- handler log जाँचें। क्या आपके handler के कोई log statement फ़ायर हो रहे हैं? पुष्टि करता है कि अनुरोध आप तक पहुँचा या नहीं।
- रजिस्टर किया URL जाँचें। प्रदाता dashboard खोलें। पुष्टि करें कि URL आपके वर्तमान tunnel से मेल खाता है और सही path की ओर इशारा करता है।
- आने वाले हेडर तुलना करें। tunnel कैप्चर आपको वही हेडर दिखाता है जो प्रदाता ने भेजे। आपके कोड द्वारा पढ़े जाने वाले से तुलना करें। हेडर केस-असंवेदनशील हैं पर उन तक पहुँचने का तरीक़ा फ़्रेमवर्क से भिन्न है — कुछ में
request.headers.get('Stripe-Signature'), अन्य मेंrequest.META['HTTP_STRIPE_SIGNATURE']। - सत्यापित करें कि सिग्नेचर समय body कच्चा है। सिग्नेचर गणना से ठीक पहले body की लंबाई प्रिंट करें। शून्य या आश्चर्यजनक रूप से छोटी हो तो किसी middleware ने इसे खा लिया।
- secret दोबारा जाँचें। runtime में env variable की dashboard से तुलना करें।
console.log(process.env.WEBHOOK_SECRET.length)— क्या लंबाई dashboard दिखाए से मेल खाती है?
हमारे अनुभव में, चरण 1 और 5 पहले दो मिनट में 80% मामले पकड़ लेते हैं।
विफल अनुरोध कैप्चर करें
यहाँ सबसे उपयोगी एकल टूल है अनुरोध कैप्चर और रीप्ले वाला tunnel। आपको प्रदाता के फिर से प्रयास का इंतज़ार नहीं करना — डीबग करते समय कैप्चर किए अनुरोध को अपने लोकल handler के विरुद्ध रीप्ले करें। हर प्रयास तुरंत।
यदि आप ऐसा tunnel उपयोग करते हैं जो अनुरोध कैप्चर नहीं करता, तो आप एक हाथ पीठ पीछे बँधे डीबग कर रहे हैं। ऐसा अपनाना जो करता है (या tcpdump चलाना, या dev सर्वर के आगे nginx रखना) पहली बार जब आप एक घंटा बचाते हैं तभी अपनी क़ीमत वसूल कर लेता है।
हर प्रदाता से 401 कैसा दिखता है
- Stripe: आपके कोड से 401 का मतलब सिग्नेचर सत्यापन विफल। Stripe dashboard डिलीवरी को विफल दिखाता है और आपका response body शामिल करता है।
- GitHub: यदि आपका handler 401 लौटाता है, GitHub डिलीवरी को विफल चिह्नित करके फिर से प्रयास करता है। हालिया डिलीवरी पृष्ठ response दिखाता है।
- Shopify: वेबहुक handler से 401 सुरक्षा के लिए ठीक है पर Shopify फिर से प्रयास करेगा। 48 घंटे में 19 लगातार विफलताओं के बाद, Shopify सब्सक्रिप्शन निष्क्रिय कर देता है।
व्यापक वेबहुक डीबगिंग संदर्भ के लिए देखें वेबहुक को लोकल कैसे डीबग करें। अंतर्निहित कैप्चर वाले tunnel के लिए PortPreview वेटलिस्ट में शामिल हों।