localhost पर Mailgun webhook कैसे टेस्ट करें

परीक्षण करने के लिए Mailgun स्थानीयहोस्ट पर वेबहुक, अपने स्थानीय हैंडलर को उजागर करें npx portpreview PORT, आवश्यक Mailgun घटना प्रकारों के लिए परिणामी HTTPS समापन बिंदु को कॉन्फ़िगर करें, और घटना को स्वीकार करने से पहले पेलोड के टाइमस्टैम्प, टोकन और HMAC-SHA256 हस्ताक्षर को सत्यापित करें।

क्या Mailgun वेबहुक रिपोर्ट

Mailgun एक कॉन्फ़िगर घटना होने पर एक JSON पेलोड के साथ HTTP या HTTPS POST भेजता है। वर्तमान घटना प्रकारों में शामिल हैं accepted, delivered, temporary_fail, permanent_fail, opened, clicked, स्पैम शिकायतें और सदस्यता रद्द करें। जब संबंधित ट्रैकिंग सक्षम हो जाती है तो ट्रैकिंग-निर्भर घटनाएं केवल दिखाई देती हैं।

एक वर्तमान Mailgun Send वेबहुक शरीर एक है signature साथ में event-dataघटना डेटा में फ़ील्ड जैसे फ़ील्ड शामिल हैं event, id, timestampघटना के प्रकार के आधार पर संदेश हेडर, प्राप्तकर्ता सूचना, टैग और वितरण विवरण। दस्तावेज़ित क्षेत्रों के खिलाफ कोड और अनुपस्थित वैकल्पिक गुणों को सहन करना। Mailgun का आधिकारिक पेलोड उदाहरण अनुबंध परीक्षण के लिए सबसे अच्छा जुड़नार हैं।

Mailgun के साथ एक Mailgun Send वेबहुक को भ्रमित न करें चेतावनी अलर्ट एक अलग हस्ताक्षर कुंजी का उपयोग करते हैं और पूरे POST बॉडी को एक अलग हस्ताक्षर करते हैं। X-Sign हेडर इस गाइड में वेबहुक भेजें: पेलोड में हस्ताक्षर क्षेत्र और खाता Webhook Signing Key।

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

कच्चे JSON शरीर पर हस्ताक्षर करने वाली योजनाओं के विपरीत, Mailgun Send की दस्तावेज गणना हस्ताक्षर ऑब्जेक्ट के टाइमस्टैम्प और टोकन का उपयोग करती है। इसलिए मानक JSON पार्सिंग उपयुक्त है। निम्नलिखित Express हैंडलर HMAC को सत्यापित करता है, फिर से खेलना-age चेक करता है, और निश्चित रूप से घटना को स्वीकार करता है।

import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.use(express.json({ limit: '1mb' }));

function verifyMailgunSignature({ timestamp, token, signature }) {
  if (!timestamp || !token || !signature) return false;

  const expected = crypto
    .createHmac('sha256', process.env.MAILGUN_WEBHOOK_SIGNING_KEY)
    .update(String(timestamp) + String(token))
    .digest('hex');

  const expectedBytes = Buffer.from(expected, 'hex');
  const actualBytes = Buffer.from(String(signature), 'hex');
  return expectedBytes.length === actualBytes.length &&
    crypto.timingSafeEqual(expectedBytes, actualBytes);
}

app.post('/webhooks/mailgun', async (req, res) => {
  const signing = req.body?.signature;
  const event = req.body?.['event-data'];

  if (!signing || !event || !verifyMailgunSignature(signing)) {
    return res.status(406).send('invalid webhook');
  }

  const ageSeconds = Math.abs(Date.now() / 1000 - Number(signing.timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > 15 * 60) {
    return res.status(406).send('stale webhook');
  }

  await acceptOnce({
    eventId: event.id,
    replayToken: signing.token,
    payload: event,
  });
  return res.sendStatus(200);
});

app.listen(3000);

15 मिनट की खिड़की एक आवेदन नीति है, एक Mailgun-प्रबंधित मूल्य नहीं है। Mailgun यह जांचने की सलाह देता है कि टाइमस्टैम्प वर्तमान समय से बहुत दूर नहीं है लेकिन अत्यधिक आक्रामक होने के खिलाफ चेतावनी देता है क्योंकि प्रसव में देरी हो सकती है। एक ऐसी विंडो चुनें जो आपकी कतार और घटना की वसूली आवश्यकताओं को फिट करती है, वैध अस्वीकृति की निगरानी करती है और इसे जानबूझकर समायोजित करती है।

एक गुप्त प्रबंधक या पर्यावरण चर में Webhook Signing Key स्टोर करें, कभी स्रोत नियंत्रण में नहीं। Mailgun वेबहुक गाइड को सुरक्षित करना सटीक गणना को परिभाषित करता है: किसी विभाजक, गणना के साथ समय-समय पर टाइमस्टैम्प और टोकन को जोड़नाHMAC-SHA256उपयोग करनावेबहुक साइनिंग कुंजी, और साथ में हेक्साडेसिमल पाचन की तुलना signature।

2. HTTP पर स्थानीय होस्ट को उजागर करें

आवेदन 3000 पोर्ट पर सुनने के साथ, रन:

npx portpreview 3000

सार्वजनिक एचटीटीपी मूल के स्थानीय मार्ग को प्रस्तुत करें। उदाहरण के लिए:

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

परीक्षण के दौरान चल रहे आवेदन और सुरंग दोनों को छोड़ दें।मेलगनएक सार्वजनिक रूप से सुलभ यूआरएल की जरूरत है; localhost, एक निजी लैन पता, और एक स्व-सिग्न विकास प्रमाण पत्र उपयुक्त दूरस्थ गंतव्य नहीं हैं। PortPreview सार्वजनिक HTTPS को समाप्त करता है और आपके स्थानीय बंदरगाह के अनुरोध को अग्रेषित करता है।

3. कॉन्फ़िगर करें Mailgun इवेंट यूआरएल

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

1. इच्छित खाते या डोमेन भेजने के लिए वेबहुक क्षेत्र खोलें।
2. इस तरह के रूप में एक घटना प्रकार चुनें delivered या permanent_fail।
3. पूर्ण PortPreview HTTPS समापन बिंदु जोड़ें।
4. प्रत्येक घटना के लिए अपने हैंडलर समर्थन टाइप करें।
5. एक परीक्षण या वास्तविक संदेश भेजें और स्थानीय अनुरोध और एप्लिकेशन लॉग का निरीक्षण करें।

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

कैसे Mailgun हस्ताक्षर सत्यापन कार्य

The signature वस्तु में शामिल हैं:

• timestamp: सेकंड में यूनिक्स समय।
• token: एक यादृच्छिक रूप से उत्पन्न 50-character स्ट्रिंग।
• signatureएक hexadecimal HMAC है।
• parent-signature: वैकल्पिक रूप से एक subaccount से एक घटना के लिए मौजूद है, जो Mailgun द्वारा वर्णित प्राथमिक खाता संबंध के खिलाफ सत्यापन की अनुमति देता है।

सामान्य खाता हस्ताक्षर के लिए, गणना HMAC-SHA256(signingKey, timestamp + token)कोई विभाजक नहीं है और event-data JSON इस दस्तावेज का हिस्सा नहीं है Mailgun Send गणना। समान लंबाई की जांच के बाद एक समय से सुरक्षित समारोह के साथ डीकोडेड बाइट्स की तुलना करें। एक सादे === तुलना सरल है, लेकिन टाइमिंग-सेफ तुलना सुरक्षित उत्पादन डिफ़ॉल्ट है।

एक प्रामाणिक HMAC साबित करता है कि हस्ताक्षर कुंजी रखने वाले एक पार्टी ने हस्ताक्षर का उत्पादन किया। यह साबित नहीं होता कि इस डिलीवरी को फिर से खेलना नहीं है। Mailgun विशेष रूप से टोकन लेने की सलाह देता है और बाद में एक ही टोकन के अनुरोध को अस्वीकार करता है। टाइमस्टैम्प-एज चेक सीमा कितनी देर तक वैध अनुरोध उपयोगी रहता है। दोनों नियंत्रणों का उपयोग करें: फिर से खेलना और ताजगी के लिए उचित समय की खिड़की के लिए एक अद्वितीय टोकन बाधा।

डिडुप्लिकेट दोनों प्रसव और प्रभाव

दो टिकाऊ विशिष्टता बाधाएं रखें: हस्ताक्षर टोकन के लिए एक और Mailgun के लिए एक event-data.idToken एक समान हस्ताक्षरित वितरण फिर से खेलना पकड़ता है। घटना ID व्यापार तर्क की रक्षा करता है यदि एक ही घटना दूसरे वैध वितरण संदर्भ में दिखाई देती है। प्रदाता और खाता या पर्यावरण दोनों द्वारा नेमस्पेस।

async function acceptOnce({ eventId, replayToken, payload }) {
  await db.transaction(async (tx) => {
    const tokenWasNew = await tx.webhookTokens.insertIfAbsent({
      provider: 'mailgun',
      token: replayToken,
    });
    if (!tokenWasNew) return;

    const eventWasNew = await tx.webhookEvents.insertIfAbsent({
      provider: 'mailgun',
      eventId,
      receivedAt: new Date(),
    });
    if (!eventWasNew) return;

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

डेटाबेस अद्वितीय अनुक्रमणिकाओं के साथ सम्मिलित-if-absent संचालन पर वापस जाएँ; एक प्रविष्टि के बाद पढ़ने के लिए समवर्ती प्रसव के तहत दौड़-प्रवण है। dedup रिकॉर्ड और कतार नौकरी परमाणु रूप से प्रतिबद्ध है। फिर जल्दी स्वीकार करते हैं और एक वर्कर अद्यतन संदेश राज्य, ट्रिगर अलर्ट, या एक CRM को सिंक्रनाइज़ करते हैं। देखें retry और idempotency गाइड विकल्प के लिए जब कतार और व्यापार डेटाबेस एक लेनदेन साझा नहीं कर सकता है।

Mailgun प्रतिक्रिया कोड और retry व्यवहार

Mailgun की वर्तमान भेजें वेबहुक प्रलेखन तीन महत्वपूर्ण परिणाम देता है:

• 200 सफलता: Mailgun वेबहुक POST का सफल इलाज करता है और इसे पुनः प्राप्त नहीं करता है।
• 406 स्वीकार्य नहीं: Mailgun POST को अस्वीकार कर देता है और इसे वापस नहीं ले पाता है।
• कोई अन्य कोड: वितरण अधिसूचनाओं के अलावा अन्य वेबहुक के लिए, Mailgun 5 मिनट, 10 मिनट, 15 मिनट, 1 घंटे, 2 घंटे, और 4 घंटे में आठ घंटे से अधिक की वापसी।

वितरण-notification अपवाद मामले: वादा नहीं करते कि हर घटना के प्रकार सामान्य रिट्री शेड्यूल का अनुसरण करता है। नवीनतम जाँच करें स्वचालित retries प्रलेखन जब प्रसव की गारंटी आपके डिजाइन को प्रभावित करती है।

केवल एक अनुरोध के लिए उपयोग करें जिसे आप जानबूझकर स्थायी रूप से अस्वीकार करते हैं, जैसे कि अमान्य हस्ताक्षर या पॉलिसी के बाहर फिर से खेलना। क्षणिक डेटाबेस और कतार विफलताओं के लिए 500 या 503 का उपयोग करें ताकि पात्र वेबहुक प्रकार पुनः प्राप्त कर सकें। टिकाऊ स्वीकृति के बाद ही 200 लौटें। अट्रैक्ड पृष्ठभूमि कार्य शुरू करते समय 200 लौटना इस घटना को खो सकता है अगर प्रक्रिया निकलती है।

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

Computed HMAC कभी मैच नहीं

पुष्टि करें कि आप उपयोग कर रहे हैं Webhook Signing Keyनहीं, एक API कुंजी, SMTP पासवर्ड, या चेतावनी कुंजी संकेत। हस्ताक्षर ऑब्जेक्ट के टाइमस्टैम्प और टोकन को बिना किसी सीमक के अलग-अलग करें। एक लोअरकेस हेक्साडेसिमल SHA-256 का उत्पादन। इसके अलावा यह सत्यापित करें कि आपके ढांचे को हाइफेनेटेड नाम नहीं दिया गया है event-data संपत्ति; ब्रैकेट नोटेशन उस गलती से बच जाता है।

हैंडलर वर्तमान JSON के बजाय फॉर्म फ़ील्ड प्राप्त करता है

जाँच करें कि कौन से Mailgun फीचर और समापन बिंदु संस्करण ने अनुरोध किया। एक वर्तमान में एक विरासत पेलोड ट्यूटोरियल को अंधा रूप से लागू नहीं करें वेबहुक भेजें। लॉग सामग्री प्रकार, शीर्ष स्तर के क्षेत्र के नाम, और लॉगिंग संदेश सामग्री या रहस्यों के बिना विकास में शरीर की लंबाई, फिर अपने खाते और एकीकरण के लिए दस्तावेज अनुबंध को लागू करें।

Mailgun

तार पर भेजे गए वास्तविक स्थिति का निरीक्षण करें। डेटाबेस करने के बाद एक अपवाद 500 में प्रतिक्रिया को बदल सकता है, जिससे एक और प्रयास हो सकता है। यही कारण है कि घटना आईडी और टोकन आवेषण अद्वितीय और टिकाऊ होना चाहिए। यदि कोई अनुरोध स्थायी रूप से अमान्य है, तो 406 लौटें; यदि विफलता क्षणिक है, तो सेवा को ठीक करें और काम करने के लिए पुनः प्रयास करें।

कोई घटना स्थानीय होस्ट तक नहीं पहुंचती

पुष्टि करें कि यूआरएल सही खाते या डोमेन से जुड़ा हुआ है और सटीक घटना प्रकार का उत्पादन किया जा रहा है। A delivered यूआरएल प्राप्त नहीं होगा opened कार्यक्रम। जांचें कि स्थानीय प्रक्रिया और सुरंग अभी भी सक्रिय है और यह कॉन्फ़िगर किया गया पथ है /webhooks/mailgunTo make a good way. स्थानीय वेबहुक डिबगिंग गाइड रूटिंग और एप्लिकेशन त्रुटियों से प्रदाता विन्यास को अलग करने के लिए।

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

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

Mailgun वेबहुक अनुरोधों पर एक वैकल्पिक TLS क्लाइंट प्रमाणपत्र भी प्रदान करता है जब आपका प्राप्त सर्वर मान्य TLS है। यह परिवहन स्तर की वैधता प्रदान कर सकता है, लेकिन यह पेलोड HMAC सत्यापन, रिप्ले कंट्रोल और एप्लिकेशन प्राधिकरण को प्रतिस्थापित नहीं करता है। अपने खतरे के मॉडल के अनुसार परत नियंत्रण।

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

1. एक वैध हस्ताक्षरित स्थिरता प्रदान करें और एक टिकाऊ घटना प्लस 200 प्रतिक्रिया की पुष्टि करें।
2. हस्ताक्षर को बदलने के बिना टोकन बदलें और कोई घटना लिखने के साथ एक 406 की पुष्टि करें।
3. सटीक मान्य शरीर को फिर से खेलना और कोई दूसरा काम या साइड इफेक्ट की पुष्टि नहीं करना।
4. अपने कॉन्फ़िगर विंडो के बाहर टाइमस्टैम्प के साथ एक वैध हस्ताक्षर भेजें और इच्छित अस्वीकृति को सत्यापित करें।
5. एक अस्थायी डेटाबेस त्रुटि को मजबूर करें, एक गैर-200 / गैर-406 प्रतिक्रिया की पुष्टि करें, फिर डेटाबेस को पुनर्स्थापित करें और एक सफल स्वीकृति सत्यापित करें।
6. प्रत्येक कॉन्फ़िगर किए गए Mailgun इवेंट टाइप का प्रयोग करें क्योंकि पेलोड फ़ील्ड और रीट्री उम्मीदें अलग हैं।

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