localhost पर SendGrid Event Webhook कैसे टेस्ट करें

स्थानीयहोस्ट पर एक SendGrid Event Webhook का परीक्षण करने के लिए, स्थानीय रूप से अपने हैंडलर को चलाएं, अपने बंदरगाह को उजागर करें npx portpreview PORT, परिणामी HTTPS समापन बिंदु को SendGrid के पोस्ट यूआरएल के रूप में दर्ज करें और अपनी घटनाओं को संसाधित करने से पहले Signed Event Webhook सार्वजनिक कुंजी के साथ हर अनुरोध को सत्यापित करें।

SendGrid Event Webhook क्या भेजता है

Event Webhook रिपोर्ट के बाद क्या होता है SendGrid एक संदेश स्वीकार करता है। उपलब्धता की घटनाओं में शामिल हैं processed, delivered, deferred, bounce, और droppedसगाई की घटनाओं में शामिल हैं open, click, स्पैम रिपोर्ट और सदस्यता परिवर्तन। सटीक क्षेत्र घटना के प्रकार के अनुसार भिन्न होते हैं, इसलिए मुख्य रूप से मुख्य रूप से शुरू होता है। event और वैकल्पिक फ़ील्ड वैकल्पिक के रूप में व्यवहार करते हैं।

एक अनुरोध निकाय एक JSON है सरणीजरूरी नहीं कि एक वस्तु। SendGrid एक एकल POST में कई घटनाओं को रख सकता है। एक हैंडलर जो मानता है req.body.event चुपचाप बैच को याद करेंगे। आधिकारिक Event Webhook संदर्भ घटना के नाम और फ़ील्ड शामिल हैं sg_event_id और sg_message_id।

तथ्यों के रूप में घटनाओं का उपयोग करें, आदेश नहीं। उदाहरण के लिए, एक delivered घटना संदेश की स्थिति को अपडेट कर सकती है, जबकि एक क्लिक एक सगाई रिकॉर्ड को पेश कर सकता है। एक क्लिक हैंडलर को बाद में अनसब्सक्राइब स्टेट को ओवरराइट करने से बचें क्योंकि अनुरोधों को ऑर्डर से बाहर निकाला गया।

1. स्थानीय समापन बिंदु बनाएं

यह Express उदाहरण जानबूझकर एक कच्चे शरीर पार्सर केवल SendGrid मार्ग पर लागू होता है। हस्ताक्षर सत्यापन सटीक बाइट्स पर निर्भर करता है SendGrid हस्ताक्षरित; पीछा और फिर से सीरियलिंग JSON उन बाइट्स को बदल सकता है।

import express from 'express';
import { EventWebhook, EventWebhookHeader } from '@sendgrid/eventwebhook';

const app = express();
const verifier = new EventWebhook();
const publicKey = verifier.convertPublicKeyToECDSA(
  process.env.SENDGRID_WEBHOOK_PUBLIC_KEY,
);

app.post(
  '/webhooks/sendgrid',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.get(EventWebhookHeader.SIGNATURE());
    const timestamp = req.get(EventWebhookHeader.TIMESTAMP());

    if (!signature || !timestamp || !verifier.verifySignature(
      publicKey,
      req.body,
      signature,
      timestamp,
    )) {
      return res.status(403).send('invalid signature');
    }

    let events;
    try {
      events = JSON.parse(req.body.toString('utf8'));
    } catch {
      return res.status(400).send('invalid JSON');
    }
    if (!Array.isArray(events)) {
      return res.status(400).send('expected an event array');
    }

    await enqueueNewEvents(events);
    return res.sendStatus(204);
  },
);

app.use(express.json());
app.listen(3000);

आधिकारिक सहायक स्थापित करें npm install @sendgrid/eventwebhookमाउंट वैश्विक express.json() इस मार्ग के बाद, या स्पष्ट रूप से इस पथ को बाहर कर दें। वही नियम Next.js, Fastify, NestJS, सर्वर रहित कार्यों और एपीआई गेटवे में लागू होता है: सत्यापन सफल होने तक मूल शरीर को स्ट्रिंग या बाइट बफर के रूप में बनाए रखें। आधिकारिक SendGrid नोड भंडार में एक मिलान है हस्ताक्षरित Event Webhook उदाहरण।

2. देना SendGrid एक HTTPS यूआरएल

एप्लिकेशन को चलाने के बाद दूसरे टर्मिनल को खोलें:

npx portpreview 3000

PortPreview एक सार्वजनिक HTTPS मूल प्रिंट करता है। अगर यह है https://example.portpreview.dev, पूरा पोस्ट यूआरएल है:

https://example.portpreview.dev/webhooks/sendgrid

मार्ग बिल्कुल मिलान करना चाहिए। परीक्षण करते समय सुरंग प्रक्रिया को जीवित रखें। एक सुरंग यातायात को आगे बढ़ाता है; यह आपके स्थानीय सर्वर को प्रतिस्थापित नहीं करता है, इसलिए कनेक्शन विफलताओं का मतलब आमतौर पर ऐप को बंद कर दिया जाता है, किसी अन्य बंदरगाह को सुनने या सुरंग तक नहीं पहुंच सकता है।

3. Event Webhook को SendGrid में कॉन्फ़िगर करें

1. SendGrid UI में, खुला सेटिंग्स > मेल सेटिंग्स।
2. वेबहुक सेटिंग्स के तहत, खुला Event Webhook चुनना नई वेबहुक बनाएँ।
3. इसे सक्षम करें, PortPreview URL को पोस्ट URL के रूप में जोड़ें, और केवल उन कार्यों को चुनें जिनकी आपको आवेदन की आवश्यकता है।
4. सुरक्षा सुविधाओं के तहत, सक्षम Signed Event Webhook।
5. वेबहुक सहेजें, अपनी सेटिंग्स को फिर से खोलें, उत्पन्न सार्वजनिक सत्यापन कुंजी की प्रतिलिपि बनाएँ, और इसे स्टोर करें SENDGRID_WEBHOOK_PUBLIC_KEY।
6. उपयोग अपने एकीकरण का परीक्षण करेंफिर, उस घटना के प्रकार का अभ्यास करने के लिए एक वास्तविक संदेश भेजें।

SendGrid का वर्तमान सेटअप गाइड नोट्स कि परीक्षण एक वास्तविक मेल भेजने से डेटा के बजाय उदाहरण घटनाओं भेजता है। हस्ताक्षर सत्यापन परीक्षण से पहले सेव करें: Signed Event Webhook कॉन्फ़िगरेशन को सहेजने पर कुंजी जोड़ी उत्पन्न होती है।

कैसे SendGrid के हस्ताक्षरित वेबहुक सत्यापन कार्य

Signed Event Webhook ECDSA का उपयोग करता है। SendGrid निजी कुंजी रखता है और आपको संबंधित सार्वजनिक सत्यापन कुंजी प्रदर्शित करता है। प्रत्येक प्रसव में शामिल हैं X-Twilio-Email-Event-Webhook-Signature और X-Twilio-Email-Event-Webhook-Timestampसत्यापन में कच्चे पेलोड बाइट्स और एक SHA-256 हैश के साथ समाहित टाइमस्टैम्प को शामिल किया गया है; हस्ताक्षर Base64-encoded है। आधिकारिक सहायक सार्वजनिक कुंजी रूपांतरण, हस्ताक्षर डिकोडिंग, हैशिंग और ECDSA सत्यापन को संभालता है।

यह सममित सत्यापन है: प्रदर्शित मान एक सार्वजनिक कुंजी है, नहीं एक HMAC गुप्त है। पेलोड के माध्यम से नहीं चलाएं JSON.stringify(), व्हाइटस्पेस को ट्रिम करें, एक नई लाइन का पालन करें, या एक समय में एक सरणी तत्व को सत्यापित करें। पहले पूर्ण अनुरोध बाइट्स को सत्यापित करें, फिर सरणी को पार करें। SendGrid सुरक्षा-फ़ीचर प्रलेखन एल्गोरिथ्म और हेडर के लिए।

एक वैध हस्ताक्षर यह स्थापित करता है कि हस्ताक्षरित बाइट SendGrid की निजी कुंजी धारक से आए थे और इसे परिवर्तित नहीं किया गया था। यह घटना प्रसंस्करण idempotent नहीं बनाता है, मनमाने ढंग से कार्रवाई को अधिकृत करता है, या साबित करता है कि एक घटना नया है। वे अलग नियंत्रण हैं।

बैच प्रसंस्करण विचारक

SendGrid retries असफल POSTs, और नेटवर्क एक सफल प्रतिक्रिया खो सकते हैं। इसलिए, डुप्लिकेट डिलीवरी सामान्य है। प्रत्येक घटना का उपयोग करें sg_event_id प्राथमिक deduplication कुंजी के रूप में, एक अद्वितीय डेटाबेस बाधा के साथ। यदि आपका उत्पाद एकाधिक SendGrid खातों या वातावरण को जोड़ती है, तो नाम प्रदाता और खाता या पर्यावरण द्वारा कुंजी को स्थान देता है।

async function enqueueNewEvents(events) {
  for (const event of events) {
    await db.transaction(async (tx) => {
      const inserted = await tx.webhookReceipts.insertIfAbsent({
        provider: 'sendgrid',
        eventId: event.sg_event_id,
        receivedAt: new Date(),
      });
      if (!inserted) return;

      await tx.jobs.enqueue({
        type: 'process-sendgrid-event',
        payload: event,
      });
    });
  }
}

रसीद डालने और टिकाऊ enqueue एक साथ करना चाहिए। बैच के बाद केवल 2xx वापस लौटेंस्वीकार करनायदि एक घटना दूसरों के लिए प्रतिबद्ध होने के बाद विफल हो जाती है, तो एक गैर -2xx प्रतिक्रिया पूरी तरह से वापसी के लिए अनुरोध का कारण बन सकती है; deduplication अगले प्रयास पहले से ही घटनाओं को छोड़ देता हैस्वीकार करनाऔर सुरक्षित रूप से जारी रखें। इन-मेमोरी का उपयोग न करें Set उत्पादन में क्योंकि पुनरारंभ इसे मिटा देता है और कई उदाहरण इसे साझा नहीं करते हैं। व्यापक वेबहुक रीट्री और idempotency गाइड टिकाऊ पैटर्न को कवर करता है।

स्टेटस कोड चुनने से पहले रिट्रीज़ को समझें

SendGrid के Event Webhook प्रलेखन के अनुसार, एक 2xx प्रतिक्रिया POST सफल रही है। एक गैर-2xx प्रतिक्रिया घटना के बाद 24 घंटे तक के लिए अंतराल में वृद्धि करने के कारण होता है; यह प्रत्येक नए असफल घटना के लिए एक रोलिंग विंडो है। उस व्यवहार का मतलब है कि एक स्थायी हस्ताक्षर विफलता भी बार-बार प्रयास उत्पन्न कर सकती है, जबकि एक घटना के लिए 2xx वापस लौटते समय आप इसे कभी संग्रहीत नहीं करते हैं।

• 2xx: पूरा बैच प्रमाणित किया गया है और durably accepted, या हर घटना पहले से ही जाना जाता है।
• 4xx: विकृत या अनधिकृत इनपुट। केवल सुरक्षित निदान लॉग करें; उम्मीद है कि SendGrid का सामान्य गैर-2xx retry व्यवहार है।
• 5xx: एक क्षणिक डेटाबेस, कतार या अनुप्रयोग विफलता जिसे पुनर्प्राप्त किया जाना चाहिए।

अनुरोध पथ को संक्षिप्त रखें: सत्यापित करें, बाहरी आकार को मान्य करें, परमाणु रूप से deduplicate और enqueue, फिर जवाब दें। कार्यकर्ताओं में ईमेल एनालिटिक्स अपडेट, सीआरएम सिंक्रनाइज़ेशन और अधिसूचनाएं करना।

समस्या निवारण स्थानीय SendGrid वेबहुक

हस्ताक्षर हमेशा अमान्य है

सबसे आम कारण JSON मिडलवेयर है जो सत्यापन से पहले शरीर का उपभोग करता है। पुष्टि करें कि सत्यापनकर्ता को मूल प्राप्त होता है Buffer, किसी भी अग्रणी या अनुयायी व्हाइटस्पेस सहित। फिर जांचें कि सार्वजनिक कुंजी इस सटीक Event Webhook विन्यास से संबंधित है और दोनों Twilio हेडर ऐप को अपरिवर्तित तक पहुंचते हैं। अपने पर्यावरण को बदलने के बाद स्थानीय प्रक्रिया को फिर से शुरू करें।

टेस्ट इंटीग्रेशन सफल होता है, लेकिन वास्तविक घटनाओं दिखाई नहीं देते हैं

सत्यापित करें कि वेबहुक सक्षम है और वांछित कार्रवाई का चयन किया जाता है। ओपन को ओपन ट्रैकिंग की आवश्यकता होती है, और क्लिक को क्लिक ट्रैकिंग की आवश्यकता होती है। इसके अलावा यह भी याद रखें कि परीक्षण अनुरोध में उदाहरण शामिल हैं; उत्पादन जैसे क्षेत्रों और अनुक्रमण को मान्य करने के लिए वास्तविक भेजने का उपयोग करें।

अंतिम बिंदु रिटर्न 404 या 502

404 के लिए, कॉन्फ़िगर किए गए पथ की तुलना करें /webhooks/sendgridगेटवे त्रुटियों के लिए, सुनिश्चित करें कि स्थानीय ऐप उसी पोर्ट पर चल रहा है जिसे PortPreview में पारित किया गया है। यदि अनुरोध 500 तक पहुंचते हैं, तो स्थानीय लॉग का निरीक्षण करें और अस्थायी रूप से हैंडलर को सत्यापन प्लस टिकाऊ कैप्चर करने के लिए कम करें।

घटनाओं को डुप्लिकेट या ऑर्डर से बाहर किया जाता है

यह एक वितरण प्रणाली वास्तविकता है, यह सबूत नहीं है कि सुरंग डुप्लिकेट यातायात है। द्वारा Deduplicate sg_event_id, जहां संभव हो राज्य संक्रमण monotonic बनाते हैं, और अलग से समय प्राप्त करने से घटना समय स्टोर। उपयोग स्थानीय वेबहुक डीबगिंग वर्कफ़्लो परिवहन, प्रमाणीकरण और व्यापार-लौकिक विफलताओं को अलग करना।

स्थानीय और उत्पादन उपयोग के लिए सुरक्षा चेकलिस्ट

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

SendGrid भी Event Webhook सुरक्षा के लिए OAuth 2.0 का उपयोग कर सकते हैं, या तो अकेले या हस्ताक्षर के साथ। यदि आपकी तैनाती को बियरर-टोकन लाइफसाइकल कंट्रोल की आवश्यकता होती है, तो टोकन विनिमय को रोकने के बजाय आधिकारिक सुरक्षा गाइड का पालन करें। हस्ताक्षर सत्यापन मूल्यवान रहता है क्योंकि यह सटीक टाइमस्टैम्प और पेलोड बाइट्स को बांधता है।

एक उत्पादन तैयारी स्वीकृति परीक्षण

1. एक हस्ताक्षरित परीक्षण अनुरोध भेजें और 2xx प्रतिक्रिया की पुष्टि करें।
2. एक पेलोड बाइट बदलें और कोई डेटाबेस लिखने के साथ एक 403 की पुष्टि करें।
3. समान वैध अनुरोध को फिर से खेलना और किसी डुप्लिकेट जॉब या बिज़नेस एक्शन की पुष्टि नहीं करना।
4. एक सरणी के बजाय एक JSON ऑब्जेक्ट भेजें और नियंत्रित 400 की पुष्टि करें।
5. डेटाबेस को संक्षेप में बंद करें, एक 5xx की पुष्टि करें, इसे बहाल करें और सत्यापित करें कि एक बार फिर से प्रयास करना accepted है।
6. एक वास्तविक ईमेल भेजें और चयनित वितरण और सगाई की घटनाओं की पुष्टि उसी रास्ते का पालन करें।

एक बार जब ये चेक पास हो जाते हैं, तो सत्यापन और विचारधारा तर्क को बदलने के बिना उत्पादन के लिए समापन बिंदु को स्थानांतरित करें। गहन क्रिप्टोग्राफिक विफलता मोड के लिए, पढ़ा वेबहुक हस्ताक्षर सत्यापन गाइड।