localhost पर Supabase Database Webhooks कैसे टेस्ट करें

स्थानीय होस्ट पर Supabase Database Webhook का परीक्षण करने के लिए उपयोग करें host.docker.internal जब दोनों Supabase और आपके रिसीवर अपनी मशीन पर चलते हैं, या एक सार्वजनिक HTTPS सुरंग का उपयोग करते हैं जब एक होस्टेड Supabase परियोजना को आपके स्थानीय ऐप को कॉल करना होगा। स्थानीय Postgres Docker में चलाता है, जहां localhost इसका मतलब है कि डेटाबेस कंटेनर, जबकि होस्ट किया गया Supabase को इंटरनेट-रिपोर्टेबल URL की आवश्यकता होती है।

Supabase Database Webhooks

Database Webhooks Postgres पर प्रतिक्रिया करता है INSERT, UPDATE, और DELETE एक चयनित तालिका पर संचालन। Supabase उन्हें ट्रिगर के आसपास एक अतुल्यकालिक आवरण के रूप में वर्णित करता है, जिसका उपयोग ट्रिगर्स के आसपास होता है। pg_net विस्तार। वह लेनदेन जो पंक्ति बदलता है, वह आपके रिसीवर के लिए अपने व्यवसाय तर्क को खत्म करने की प्रतीक्षा नहीं करता है, जो युग्मन को कम करता है लेकिन इसका मतलब है कि रिसीवर को पालने योग्य और असफलता से सावधान रहना चाहिए।

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

स्थानीय स्टैक बनाम होस्ट प्रोजेक्ट

एक स्थानीय अनुप्रयोग के लिए स्थानीय Supabase: Docker होस्ट का उपयोग करें

जब आप दौड़ते हैं supabase start, Postgres एक कंटेनर के अंदर है। एक वेबहुक यूआरएल जैसे http://localhost:3000/api/supabase-db-hook उस कंटेनर में वापस लूप और आमतौर पर विफल रहता है। Supabase का आधिकारिक Database Webhooks प्रलेखन लक्ष्य कहना host.docker.internal:

http://host.docker.internal:3000/api/supabase-db-hook

इस मार्ग को सार्वजनिक सुरंग की आवश्यकता नहीं है। Linux इंजन पर जहां होस्टनाम अनुपलब्ध है, अपने Docker सेटअप या अपनी मशीन के लैन पते द्वारा समर्थित होस्ट-गेटवे मैपिंग का उपयोग करें, जैसा कि Supabase डॉक्स सुझाव देते हैं। एक कंटेनर से पुष्टि करें, न केवल मेजबान ब्राउज़र से।

एक स्थानीय ऐप में Supabase होस्ट किया गया: HTTPS का उपयोग करें

क्लाउड डेटाबेस आपके लैपटॉप के Docker होस्टनाम या निजी लूपबैक पते को हल नहीं कर सकता है। स्थानीय ऐप शुरू करें और चलाएं npx portpreview 3000, फिर कॉन्फ़िगर करें:

https://your-subdomain.portpreview.dev/api/supabase-db-hook

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

एक रिसीवर बनाएं जो साझा रहस्य को मान्य करता है

प्रदाता के विपरीत जो एक अनिवार्य HMAC हेडर को परिभाषित करते हैं, Database Webhook एक विन्यास योग्य आउटबाउंड HTTP अनुरोध है। एक गुप्त हेडर के साथ एंडपॉइंट को सुरक्षित रखें जिसे आप वेबहुक पर उसी हेडर को नियंत्रित और कॉन्फ़िगर करते हैं। TLS इसे पारगमन में सुरक्षित रखता है; एक स्थिर समय की तुलना आपके आवेदन के माध्यम से गुप्त-समाप्त समय को लीक करने से बचाती है।

// app/api/supabase-db-hook/route.ts
import crypto from 'node:crypto';

function safeEqual(a: string, b: string) {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length &&
    crypto.timingSafeEqual(left, right);
}

export async function POST(request: Request) {
  const supplied = request.headers.get('x-webhook-secret') ?? '';
  const expected = process.env.SUPABASE_DB_WEBHOOK_SECRET ?? '';

  if (!expected || !safeEqual(supplied, expected)) {
    return new Response('unauthorized', { status: 401 });
  }

  const payload = await request.json();
  if (!['INSERT', 'UPDATE', 'DELETE'].includes(payload.type)) {
    return new Response('unsupported event', { status: 400 });
  }

  await recordDelivery(payload);
  return new Response('accepted', { status: 200 });
}

एक साझा हेडर गुप्त के ज्ञान को साबित करता है लेकिन क्रिप्टोग्राफिक रूप से उस रहस्य को शरीर से बांधता नहीं है। यदि शरीर के स्तर के छेड़छाड़ के सबूत की आवश्यकता होती है, तो Database Webhook को एक छोटे से विश्वसनीय Edge Function पर भेजें जो अपने स्वयं के भीतर के रहस्य को मान्य करता है, अपने चुने हुए HMAC को एक कैनोनिकल आउटबाउंड बॉडी पर पूरा करता है और इसे स्थानीय या उत्पादन उपभोक्ता को अग्रेषित करता है। नहीं X-Supabase-Signature जब तक कि आपकी खुद की अग्रेषण परत इसे बनाता है और सत्यापित करता है।

एक केंद्रित वेबहुक को कॉन्फ़िगर और ट्रिगर करें

1. एक विकास तालिका चुनें और यह तय करें कि कौन से संचालन मामले हैं।
2. डेटाबेस → वेबहुक के तहत Supabase डैशबोर्ड में Database Webhook बनाएं, स्कीमा, टेबल और संचालन का चयन करें।
3. ऊपर वर्णित स्थानीय Docker URL या सार्वजनिक सुरंग URL सेट करें।
4. जोड़ें Content-Type: application/json यादृच्छिक X-Webhook-Secret मूल्य जहां वेबहुक हेडर विन्यास उपलब्ध है।
5. रिसीवर शुरू करें और स्पष्ट रूप से लेबल परीक्षण पंक्ति डालें।
6. एक फ़ील्ड को अपडेट करें, फिर पंक्ति को हटा दें, सभी चयनित लिफाफे को सत्यापित करें।
7. स्विचन परियोजनाओं से पहले या सुरंग को बंद करने से पहले टेस्ट वेबहुक को निकालें या निष्क्रिय करें।

नाम परीक्षण पंक्तियाँ इसलिए सफाई नियतिवादी है। केवल एक अनुरोध प्राप्त करने के लिए उत्पादन ग्राहक रिकॉर्ड पर एक टेबल-वाइड एकीकरण को आग न दें।

Interpret INSERT, UPDATE और DELETE सुरक्षित रूप से

INSERT

उपयोग record नए सम्मिलित राज्य के रूप में। यदि रिसीवर कहीं और एक संबंधित वस्तु बनाता है, तो स्रोत तालिका की प्राथमिक कुंजी को एक idempotency कुंजी के रूप में स्टोर करें। मैनुअल रिप्ले या कस्टम रीट्री प्रोसेसिंग के दौरान एक सम्मिलन कार्यक्रम को फिर से वितरित किया जा सकता है।

UPDATE

तुलना record साथ old_record और केवल एकीकरण के लिए प्रासंगिक क्षेत्रों पर कार्य करते हैं। एक सामान्य अद्यतन वेबहुक टाइमस्टैम्प या असंबंधित मेटाडाटा के लिए आग लगा सकता है। फ़िल्टरिंग no-op व्यापार परिवर्तन महंगे डाउनस्ट्रीम कॉल को रोकता है।

DELETE

हटाई गई पंक्ति को वर्तमान रिकॉर्ड के बजाय पिछले डेटा द्वारा दर्शाया गया है। लापता वैकल्पिक क्षेत्रों के विलोपन हैंडलर्स को सहन करना और यह तय करना कि डाउनस्ट्रीम एक्शन विलोपन, आर्किवल या रिवोकेशन है या नहीं। लेखा परीक्षा आवश्यकताओं को संरक्षित करना।

switch (payload.type) {
  case 'INSERT':
    await mirror.upsert(payload.record.id, payload.record);
    break;
  case 'UPDATE':
    if (payload.old_record.status !== payload.record.status) {
      await syncStatus(payload.record.id, payload.record.status);
    }
    break;
  case 'DELETE':
    await mirror.archive(payload.old_record.id);
    break;
}

वितरण विश्वसनीयता एक आवेदन चिंता है

क्योंकि Database Webhooks अतुल्यकालिक नेटवर्क अनुरोध हैं, मूल पंक्ति परिवर्तन के साथ वितरित लेनदेन के रूप में रसीद का इलाज नहीं करते हैं। Postgres के बाद आपका रिमोट साइड अनुपलब्ध हो सकता है। आउटबाउंड अनुरोध परिणामों की निगरानी करें और कुछ भी है कि खो नहीं जा सकता है के लिए डिजाइन सामंजस्य।

उच्च-मूल्य वर्कफ़्लो के लिए, एक आउटबॉक्स टेबल मजबूत है: एक डेटाबेस लेनदेन में एक व्यापार परिवर्तन और आउटबॉक्स पंक्ति लिखें, फिर एक कार्यकर्ता को स्पष्ट रिट्री काउंटर, बैकऑफ और मृत-लेटर हैंडलिंग के साथ वितरित करने दें। एक Database Webhook कार्यकर्ता को सूचित कर सकता है, लेकिन आवधिक सामंजस्य अभी भी अनडिलीवर आउटबॉक्स पंक्तियों को ढूंढना चाहिए।

रिसीवर idempotent बनाते हैं। एक उपयोगी कुंजी स्रोत स्कीमा, टेबल, ऑपरेशन, प्राथमिक कुंजी और एक स्थिर पंक्ति संस्करण जैसे कि जोड़ती है updated_atसख्त गारंटी के लिए, एक आउटबॉक्स पंक्ति में एक अचल घटना UUID जोड़ें। केवल वर्तमान पंक्ति हैशिंग से बचें क्योंकि दो वैध संक्रमण समान अनुमानों का उत्पादन कर सकते हैं।

एक स्थानीय Supabase Edge Function बुला

यदि गंतव्य एक Edge Function है, तो स्थानीय Supabase स्टैक द्वारा सेवा की जाती है, तो दस्तावेज का उदाहरण है:

http://host.docker.internal:54321/functions/v1/my-function-name

आधिकारिक Edge Functions विकास गाइड उपयोग supabase functions serve [function-name] स्थानीय गर्म लोड के लिए। Edge Functions को डिफ़ॉल्ट रूप से JWT सत्यापन की आवश्यकता होती है। एक वेबहुक फ़ंक्शन के लिए जो एक उपयोगकर्ता JWT की आपूर्ति नहीं कर सकता है, उस फ़ंक्शन को जानबूझकर कॉन्फ़िगर करता है, उदाहरण के लिए, उदाहरण के लिए, उदाहरण के लिए, साथ ही साथ verify_jwt = false में supabase/config.toml, में दस्तावेज के रूप में समारोह विन्यासJWT प्रमाणीकरण को अपने गुप्त हेडर या हस्ताक्षर चेक के साथ बदलें; अकेले JWT को निष्क्रिय करने से कार्य सार्वजनिक हो जाता है।

समस्या निवारण Supabase वेबहुक स्थानीयहोस्ट डिलीवरी

कनेक्शन स्थानीय स्टैक से इनकार कर दिया

बदलें localhost साथ host.docker.internal, एप्लिकेशन को सत्यापित करें Docker से एक इंटरफेस तक पहुंची है, और पोर्ट की पुष्टि करता है। Linux पर होस्ट-गेटवे रिज़ॉल्यूशन को कॉन्फ़िगर करें या होस्ट IP का उपयोग करें। केवल एक अप्रत्याशित इंटरफ़ेस के लिए बाध्य एक सेवा अभी भी कंटेनर यातायात को अस्वीकार कर सकता है।

होस्ट की गई परियोजना कभी भी मार्ग तक नहीं पहुंचती

एक होस्ट की गई परियोजना को सार्वजनिक HTTPS सुरंग URL की आवश्यकता होती है, न कि Docker होस्टनाम। सुरंग की पुष्टि करना लाइव है और इसके यूआरएल में पूर्ण मार्ग शामिल है। अपने आप को पोस्ट करके DNS/TLS की जाँच करें।

मार्ग रिटर्न 401

कॉन्फ़िगर किए गए हेडर नाम और मूल्य की तुलना करें, व्हाइटस्पेस के अग्रणी या पीछे की ओर देखें, और पर्यावरण परिवर्तन के बाद ऐप को फिर से शुरू करें। लॉग इन करें कि हेडर मौजूद है, इसका मूल्य कभी नहीं। यदि कोई मध्यस्थ कस्टम हेडर स्ट्रिप्स करता है, तो पारंपरिक का उपयोग करें Authorization: Bearer ... हेडर और इसे स्पष्ट रूप से मान्य करते हैं।

पेलोड आकार गलत लगता है

केवल शीर्ष स्तर की चाबियाँ, ऑपरेशन, स्कीमा और टेबल को विकास में लॉग इन करें। याद रखें कि DELETE पिछली पंक्ति डेटा का उपयोग करता है और UPDATE दोनों संस्करणों को शामिल कर सकता है। अपने पार्सर को बदलने से पहले वर्तमान आधिकारिक पेलोड उदाहरणों के खिलाफ मान्य करें।

डेटाबेस अद्यतन सफल होता है लेकिन डाउनस्ट्रीम काम गायब है

यह व्यवहार एक अतुल्यकालिक डिजाइन में संभव है। Inspect webhook अनुरोध लॉग और pg_net अपने पर्यावरण में उपलब्ध निदान, फिर पहले से ही प्रतिबद्ध व्यावसायिक लेनदेन को वापस करने के बजाय पुनःप्राप्ति या सामंजस्य जोड़ें।

सुरक्षा चेकलिस्ट

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

सबसे आम स्थानीय बग नेटवर्क एड्रेसिंग है, Postgres नहीं: स्थानीय कंटेनर कॉल का उपयोग host.docker.internalक्लाउड कॉल एक सार्वजनिक सुरंग का उपयोग करते हैं। एक बार ट्रैफ़िक आने के बाद, प्रमाणीकरण और वितरण की गारंटी अलग डिजाइन समस्याओं के रूप में होती है। समीक्षा स्थानीयहोस्ट सुरंग सुरक्षा और वेबहुक विश्वसनीयता पैटर्न संवेदनशील डेटा को जोड़ने से पहले।