Next.js में Clerk webhook को स्थानीय रूप से कैसे जाँचें?

App Router का POST route बनाएँ, HTTPS tunnel से port 3000 सार्वजनिक करें, Clerk Dashboard में पूरा public route जोड़ें, CLERK_WEBHOOK_SIGNING_SECRET सेट करें और endpoint के test tab से उदाहरण भेजें।

क्या Clerk webhook route को clerkMiddleware से सुरक्षित करना चाहिए?

यह user session के बिना उपलब्ध होना चाहिए, इसलिए इस पर auth.protect() न चलाएँ। इसके बजाय verifyWebhook() और endpoint signing secret से machine request को प्रमाणित करें।

क्या Clerk verifyWebhook() से पहले raw body को parse करना चाहिए?

नहीं। मूल Request को सीधे verifyWebhook() में दें। पहले request.json() या request.text() न चलाएँ, क्योंकि helper को signed request body और headers चाहिए।

Clerk user.created की retries कैसे संभालें?

अद्वितीय Clerk user ID पर upsert करें, signed webhook message ID से duplicate हटाएँ और पहले से संसाधित event के लिए 200 लौटाएँ। गैर-ज़रूरी side effects को queue करें ताकि retries से duplicate email न जाएँ।

Next.js में localhost पर Clerk webhook की जाँच कैसे करें

Next.js में localhost पर Clerk webhook की जाँच करने के लिए App Router का POST route बनाएँ, HTTPS tunnel से port 3000 सार्वजनिक करें, public URL को Clerk webhook endpoint के रूप में जोड़ें और user data sync करने से पहले हर request को verifyWebhook() से सत्यापित करें। Clerk middleware में route को सार्वजनिक रखें: signing secret browser session के बजाय machine-to-machine request को प्रमाणित करता है।

जब Clerk वेबहुक सही सिंक टूल हो

Clerk सत्य का पहचान स्रोत बना हुआ है। एक वेबहुक तब उपयोगी होता है जब आपके एप्लिकेशन को जॉइन, खोज, रिपोर्टिंग, प्राधिकरण मेटाडेटा, या एकीकरण के लिए स्थानीय प्रक्षेपण की आवश्यकता होती है जो मांग पर Clerk से पूछताछ नहीं कर सकता है। विशिष्ट घटनाओं में शामिल हैं user.created, user.updated, और user.deleted.

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

एक सार्वजनिक Next.js ऐप राउटर एंडपॉइंट बनाएं

जोड़ना app/api/webhooks/clerk/route.ts. Clerk का करंट सिंकिंग गाइड उपयोग verifyWebhook से @clerk/nextjs/webhooks. सहायक अनुरोध का उपभोग करता है, मानक वेबहुक हस्ताक्षर की जांच करता है, और टाइप किया गया ईवेंट डेटा लौटाता है।

// app/api/webhooks/clerk/route.ts
import { verifyWebhook } from '@clerk/nextjs/webhooks';
import { NextRequest } from 'next/server';

export const runtime = 'nodejs';

export async function POST(request: NextRequest) {
  try {
    const event = await verifyWebhook(request);

    await processOnce(event, async () => {
      switch (event.type) {
        case 'user.created':
        case 'user.updated':
          await upsertClerkUser(event.data);
          break;
        case 'user.deleted':
          if (event.data.id) await archiveClerkUser(event.data.id);
          break;
      }
    });

    return new Response('accepted', { status: 200 });
  } catch (error) {
    console.error('Clerk webhook rejected', safeError(error));
    return new Response('invalid webhook', { status: 400 });
  }
}

डिफ़ॉल्ट रूप से, सहायक पढ़ता है CLERK_WEBHOOK_SIGNING_SECRET. Clerk का सत्यापितवेबहुक संदर्भ एक स्पष्ट अनुमति भी देता है signingSecret विकल्प, लेकिन पर्यावरण कॉन्फ़िगरेशन रहस्य को स्रोत में एम्बेड करने से बचाता है।

सत्र सुरक्षा से वेबहुक मार्ग को बाहर निकालें

वेबहुक अनुरोधों में आपके उपयोगकर्ता का Clerk सत्र शामिल नहीं है। यदि मिडलवेयर कॉल करता है auth.protect() प्रत्येक एपीआई पथ के लिए, हस्ताक्षर सत्यापन चलने से पहले Clerk की डिलीवरी को रीडायरेक्ट, 401, या 404 प्राप्त होता है। संरक्षित एप्लिकेशन मार्गों को स्पष्ट रूप से परिभाषित करें और छोड़ें /api/webhooks/clerk जनता।

// middleware.ts for Next.js 15 and earlier
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

const isProtectedRoute = createRouteMatcher([
  '/dashboard(.*)',
  '/api/private(.*)',
]);

export default clerkMiddleware(async (auth, request) => {
  if (isProtectedRoute(request)) await auth.protect();
});

export const config = {
  matcher: [
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico)).*)',
    '/(api|trpc)(.*)',
  ],
};

Clerk का वेबहुक डिबगिंग गाइड विशेष रूप से वेबहुक मार्गों को छोड़कर कॉल करता है। नए Next.js संस्करणों में कन्वेंशन का उपयोग किया जा सकता है proxy.ts; अपने प्रोजेक्ट में स्थापित Clerk संस्करण गाइड का पालन करें। जनता का मतलब भरोसेमंद नहीं: verifyWebhook() किसी भी कार्रवाई से पहले अनिवार्य है.

Clerk को लोकलहोस्ट से कनेक्ट करें

दौड़ना npm run dev और सत्यापित करें कि Next.js ऐप पोर्ट 3000 पर सुन रहा है।
दौड़ना npx portpreview 3000.
Clerk डैशबोर्ड में, एक वेबहुक एंडपॉइंट बनाएं https://your-subdomain.portpreview.dev/api/webhooks/clerk.
केवल आवश्यक उपयोगकर्ता, सत्र, संगठन या ईमेल ईवेंट का चयन करें।
एंडपॉइंट साइनिंग सीक्रेट को कॉपी करें CLERK_WEBHOOK_SIGNING_SECRET अपने स्थानीय परिवेश में और Next.js को पुनरारंभ करें।
समापन बिंदु का परीक्षण टैब खोलें, चुनें user.created, और उदाहरण भेजें चुनें।
पुष्टि करें कि प्रयास सफल हुआ, आपका स्थानीय मार्ग 200 लौटा, और अपेक्षित डेटाबेस पंक्ति एक बार बदल गई।

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

मॉडल उपयोगकर्ता सिंक्रनाइज़ेशन सावधानी से करें

बाहरी कुंजी के रूप में Clerk उपयोगकर्ता आईडी का उपयोग करें

इकट्ठा करना user_... एक अनोखे में clerk_user_id स्तंभ। उस कुंजी पर अप्सर्ट करें इसलिए पुनः प्रयास किया गया user.created विफल होने के बजाय एकत्रित होता है। यदि अन्य तालिकाएँ पहले से ही इसका संदर्भ देती हैं तो अपनी स्वयं की आंतरिक प्राथमिक कुंजी रखें।

प्राथमिक ईमेल जानबूझकर चुनें

Clerk उपयोगकर्ता डेटा में ईमेल पता रिकॉर्ड और एक प्राथमिक ईमेल पता आईडी शामिल है। पहला ऐरे तत्व लेने के बजाय प्राथमिक रिकॉर्ड को आईडी के आधार पर हल करें। ईमेल बदल सकता है; इसे अपरिवर्तनीय विदेशी कुंजी के रूप में उपयोग न करें।

तय करें कि हटाने का क्या मतलब है

ए user.deleted ईवेंट में बनाने या अद्यतन करने की तुलना में कम डेटा हो सकता है। अपनी नीति के अनुसार गुमनाम करने, सॉफ्ट-डिलीट करने या रिटेंशन वर्कफ़्लो शुरू करने के लिए आईडी का उपयोग करें। ब्लाइंड कैस्केडिंग विलोपन बिलिंग या ऑडिट रिकॉर्ड को नष्ट कर सकता है जिन्हें नियमों के अनुसार संरक्षित करना आवश्यक है।

हर चीज़ को आइना मत दिखाओ

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

पुनः प्रयास और ऑर्डर को हानिरहित बनाएं

Clerk दस्तावेज करता है कि एक गैर-2xx प्रतिक्रिया एक घटना पुनः प्रयास का कारण बनती है। प्रभाव लागू करने से पहले हस्ताक्षरित वेबहुक मेटाडेटा या हेडर से वेबहुक संदेश पहचानकर्ता को एक अद्वितीय रसीद के रूप में रिकॉर्ड करें। यदि आपका एसडीके हेडर में मानक वेबहुक आईडी प्रदर्शित करता है, तो उन्हें इवेंट प्रकार और टाइमस्टैम्प के साथ संरक्षित करें। पूर्ण डुप्लिकेट के लिए 200 लौटाएँ।

उपयोगकर्ता अपडेट के लिए, ईवेंट टाइमस्टैम्प की तुलना करें या अंतिम-लेखन नियमों का उपयोग करें जो पुराने ईवेंट को नए प्रोफ़ाइल डेटा को ओवरराइट करने से रोकते हैं। उच्च-मूल्य वाली स्थिति के लिए, सत्यापन के बाद Clerk से वर्तमान उपयोगकर्ता को पुनः प्राप्त करें और वेबहुक को समाधान के लिए एक संकेत के रूप में मानें। एक डेटाबेस लेनदेन में रसीद सम्मिलित करें, उपयोगकर्ता अद्यतन और आउटबॉक्स कार्य रखें।

await db.transaction(async (tx) => {
  const inserted = await tx.webhookReceipt.insertIfAbsent(messageId);
  if (!inserted) return;

  await tx.user.upsert({
    clerkUserId: clerk.id,
    primaryEmail: findPrimaryEmail(clerk),
    sourceUpdatedAt: eventTimestamp,
  });
  await tx.outbox.enqueue('profile-synced', { clerkUserId: clerk.id });
});

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

स्थानीय Clerk डिलीवरी की समस्या का निवारण करें

404, रीडायरेक्ट, या आपके हैंडलर के बजाय HTML

फ़ाइल पथ, POST निर्यात और पूर्ण टनल URL सत्यापित करें। मिडलवेयर और लोकेल पुनर्लेखन की जाँच करें। एक वेबहुक को लॉगिन रीडायरेक्ट या सीएसआरएफ फॉर्म जांच से नहीं गुजरना चाहिए। बुनियादी POST के साथ सार्वजनिक URL का परीक्षण करें; अपने रूट से हस्ताक्षर अस्वीकृति की अपेक्षा करें, फ़्रेमवर्क 404 से नहीं।

`verifyWebhook()` हमेशा फेंकता है

हस्ताक्षर रहस्य सेट करने के बाद Next.js को पुनरारंभ करें। पुष्टि करें कि रहस्य इस समापन बिंदु और वातावरण से संबंधित है। सहायक को भेजने से पहले अनुरोध निकाय को पार्स न करें, गलत तरीके से क्लोन न करें, या उसका उपभोग न करें। सुनिश्चित करें कि सुरंग मानक वेबहुक हस्ताक्षर हेडर को संरक्षित करती है।

डैशबोर्ड पुनः प्रयास दिखाता है

सटीक प्रयास प्रतिक्रिया देखें. टिकाऊ स्वीकृति के बाद ही 2xx लौटाएँ, लेकिन प्रदाता टाइमआउट से नीचे प्रसंस्करण जारी रखें। डेटाबेस माइग्रेशन, अद्वितीय-बाधा गलतियाँ, और अनुपलब्ध सेवा को समकालिक रूप से कॉल करना सामान्य 500 कारण हैं।

पंक्तियाँ डुप्लिकेट या पुरानी हैं

Clerk आईडी और वेबहुक संदेश आईडी के लिए अद्वितीय बाधाएं जोड़ें। बनाना user.created और user.updated दोनों सुरक्षित अप्सर्ट, फिर पुराने ईवेंट टाइमस्टैम्प से बचाव करें। डुप्लिकेट हैंडलिंग को साबित करने के लिए प्रत्येक फिक्स के बाद उदाहरण को दोबारा चलाएं।

सुरक्षा जाँच सूची

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

Clerk का वेबहुक सिंहावलोकन हस्ताक्षर सत्यापन और वैकल्पिक Svix IP प्रतिबंधों की व्याख्या करता है। Next.js रॉ-बॉडी फंडामेंटल और रूट व्यवहार के लिए, जारी रखें Next.js लोकलहोस्ट वेबहुक गाइड.