इनबाउंड वेबहुक्स

📥 इनबाउंड वेबहुक

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

यह कैसे काम करता है

इनबाउंड वेबहुक सिस्टम एक स्रोत और कोड मॉडल का उपयोग करता है:

1. एक स्रोत बनाएं — एक स्रोत एक बाहरी प्लेटफार्म या उपकरण का प्रतिनिधित्व करता है (जैसे "टाइपफॉर्म", "ज़ापियर", "माई क्विज़ ऐप")। प्रत्येक स्रोत को एक अद्वितीय वेबहुक URL और सुरक्षा के लिए एक गुप्त कुंजी मिलती है।
2. स्रोत में कोड जोड़ें — प्रत्येक कोड एक विशिष्ट क्रिया को परिभाषित करता है जो बीज पुरस्कार देती है (जैसे "क्विज़_पूर्ण", "फॉर्म_सबमिट", "जन्मदिन_दावा")। आप सेट करते हैं कि प्रत्येक कोड कितने बीज पुरस्कार देता है, वैकल्पिक सीमाओं के साथ।
3. POST अनुरोध भेजें — आपका बाहरी प्लेटफार्म वेबहुक URL पर कोड और ग्राहक जानकारी के साथ एक POST अनुरोध भेजता है। लॉयल्टीट्री ग्राहक को खोजता या बनाता है और स्वचालित रूप से बीज पुरस्कार देता है।

शुरू करना

चरण 1: एक वेबहुक स्रोत बनाएं

स्टोर्स → [आपका स्टोर] → इंटीग्रेशन → इनबाउंड वेबहुक पर जाएं। + स्रोत जोड़ें पर क्लिक करें और इसे एक ऐसा नाम दें जो बाहरी प्लेटफार्म का वर्णन करता हो (जैसे "टाइपफॉर्म क्विज़" या "ज़ापियर ऑटोमेशन")।

जब स्रोत बनाया जाएगा, तो आपको प्राप्त होगा:

• वेबहुक URL — वह एंडपॉइंट जहां आपका बाहरी प्लेटफार्म अनुरोध भेजेगा
• वेबहुक सीक्रेट — अनुरोधों पर हस्ताक्षर करने के लिए एक गुप्त कुंजी (सुरक्षा के लिए अनुशंसित)

चरण 2: कोड जोड़ें

प्रत्येक कोड एक विशिष्ट क्रिया का प्रतिनिधित्व करता है जिसे आप पुरस्कार देना चाहते हैं। एक बनाने के लिए अपने स्रोत पर + कोड जोड़ें पर क्लिक करें।

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

कोड और सीमाएँ समझाई गई

कोड और उनकी सीमाएँ मिलकर आपको यह नियंत्रित करने की सटीकता देती हैं कि बीज कैसे पुरस्कार दिए जाते हैं:

बीज राशि

प्रत्येक कोड की एक निश्चित बीज राशि होती है। हर बार जब वेबहुक उस कोड के साथ सक्रिय होता है, ग्राहक को ठीक उतने ही बीज मिलते हैं। उदाहरण के लिए, यदि आप "क्विज़_पूर्ण" को 5 बीज पर सेट करते हैं, तो हर योग्य वेबहुक कॉल 5 बीज पुरस्कार देती है।

प्रति ग्राहक अधिकतम बीज

यह प्रति ग्राहक प्रति कोड एक जीवनकाल सीमा निर्धारित करता है। यह कुल बीज है जो ग्राहक इस विशिष्ट कोड से कमा सकता है, न कि वे कितनी बार इसे सक्रिय कर सकते हैं।

कूलडाउन (घंटे)

एक ही कोड पर एक ही ग्राहक के लिए बीज पुरस्कारों के बीच न्यूनतम प्रतीक्षा समय निर्धारित करता है। कूलडाउन टाइमर अंतिम सफल पुरस्कार से शुरू होता है।

अनुरोध प्रारूप

अपने वेबहुक URL पर निम्नलिखित JSON शरीर के साथ एक POST अनुरोध भेजें:

{
  "code": "your_code_here",
  "customer": {
    "email": "customer@example.com",
    "shopify_customer_id": "12345",
    "first_name": "जेन",
    "last_name": "स्मिथ"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* email या shopify_customer_id में से एक आवश्यक है। जब ग्राहक पहले से लॉयल्टीट्री में मौजूद नहीं होता है, तो ईमेल आवश्यक है।

HMAC हस्ताक्षर सत्यापन (अनुशंसित)

यह सत्यापित करने के लिए कि अनुरोध वास्तव में आपके प्लेटफार्म से आ रहे हैं (और किसी ऐसे व्यक्ति से नहीं जिसने आपका वेबहुक URL खोजा है), HMAC-SHA256 का उपयोग करके अपने अनुरोधों पर हस्ताक्षर करें।

समर्थित हस्ताक्षर हेडर्स (लॉयल्टीट्री इनमें से सभी की जांच करता है):

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

हस्ताक्षर मान कच्चे हेक्स हैश या sha256= के साथ प्रीफिक्स किया जा सकता है (दोनों प्रारूप स्वीकार किए जाते हैं)।

वैकल्पिक: प्लेन टोकन प्रमाणीकरण

यदि आपके प्लेटफार्म में HMAC हस्ताक्षर करना संभव नहीं है, तो आप अपने वेबहुक सीक्रेट को X-Token हेडर में एक प्लेन टोकन के रूप में पास कर सकते हैं। लॉयल्टीट्री इसे सीधे आपके सीक्रेट से तुलना करेगा।

उदाहरण: Node.js के साथ हस्ताक्षर करना

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'क्विज़_पूर्ण',
  customer: { email: 'jane@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'your_webhook_secret')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

उदाहरण: Python के साथ हस्ताक्षर करना

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "क्विज़_पूर्ण",
    "customer": {"email": "jane@example.com"}
})
signature = hmac.new(
    b'your_webhook_secret',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

उदाहरण: cURL का उपयोग करना (परीक्षण के लिए)

curl -X POST https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "X-Token: your_webhook_secret" \
  -d '{"code":"क्विज़_पूर्ण","customer":{"email":"jane@example.com"}}'

प्रतिक्रिया प्रारूप

सफल प्रतिक्रिया (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

सफल लेकिन सीमित (200)

जब एक कूलडाउन या अधिकतम बीज सीमा पुरस्कार को रोकती है, तो आपको अभी भी 200 प्रतिक्रिया मिलती है लेकिन 0 बीज और एक स्पष्टीकरण के साथ:

{
  "success": true,
  "seeds_awarded": 0,
  "message": "कूलडाउन सक्रिय। 18 घंटे में फिर से प्रयास करें।"
}

// या
{
  "success": true,
  "seeds_awarded": 0,
  "message": "इस कोड के लिए अधिकतम बीज (15) पहले ही पुरस्कार दिए जा चुके हैं।"
}

त्रुटि प्रतिक्रियाएँ

उपयोग के मामले के उदाहरण

ज़ापियर के साथ कनेक्ट करना

ज़ापियर लॉयल्टीट्री को सैकड़ों अन्य ऐप्स से कनेक्ट करने के सबसे लोकप्रिय तरीकों में से एक है। हम एक समर्पित लॉयल्टीट्री इंटीग्रेशन इन ज़ापियर ऐप स्टोर बना रहे हैं, जो सेटअप को और भी आसान बना देगा — इसे ज़ापियर मार्केटप्लेस में देखें।

इस बीच, आप अभी कनेक्ट करने के लिए ज़ापियर के वेबहुक्स बाय ज़ापियर क्रिया का उपयोग कर सकते हैं:

मेक (इंटीग्रोमैट) के साथ कनेक्ट करना

आप मेक के HTTP / मेक ए रिक्वेस्ट मॉड्यूल का उपयोग करके लॉयल्टीट्री को वेबहुक भेजने के लिए भी उपयोग कर सकते हैं। इसे ज़ापियर की तरह ही कॉन्फ़िगर करें — URL सेट करें, कोड और ग्राहक के साथ JSON शरीर जोड़ें, और X-Token हेडर में अपना सीक्रेट शामिल करें।

वेबहुक लॉग

प्रत्येक इनबाउंड वेबहुक कॉल लॉग की जाती है और आपके इंटीग्रेशन पृष्ठ के इनबाउंड वेबहुक अनुभाग में दिखाई देती है। लॉग में दिखाया जाता है:

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

अपने इंटीग्रेशन के सही तरीके से काम करने की पुष्टि करने और किसी भी समस्या को हल करने के लिए लॉग का उपयोग करें।

समस्या निवारण

सुरक्षा

• प्रत्येक स्रोत को एक अद्वितीय 64-चर वेबहुक सीक्रेट मिलता है, जो स्वचालित रूप से उत्पन्न और विश्राम में एन्क्रिप्टेड होता है
• सीक्रेट को कभी भी स्रोत सेटिंग से फिर से उत्पन्न किया जा सकता है (पुराना सीक्रेट तुरंत काम करना बंद कर देता है)
• अनुरोध पेलोड को गोपनीयता के लिए लॉग में एन्क्रिप्टेड किया जाता है
• हस्ताक्षर सत्यापन टाइमिंग-सुरक्षित तुलना का उपयोग करता है ताकि समय हमलों को रोका जा सके
• स्रोत और कोड को व्यक्तिगत रूप से अक्षम किया जा सकता है बिना उन्हें हटाए