Webhook Block - अपने चैटबॉट फ़्लो में इनबाउंड HTTP कॉल प्राप्त करें

अवलोकन

Webhook Block एक बाहरी सिस्टम को HTTP पर आपके चैटबॉट को कॉल करने देता है। इसका उपयोग दो तरीकों से किया जा सकता है: एक फ़्लो के पहले ब्लॉक के रूप में (वेबहुक स्वयं कन्वर्सेशन शुरू करता है), या एक mid-flow ब्लॉक के रूप में जो कन्वर्सेशन को रोकता है और इसे फिर से शुरू करने के लिए एक बाहरी कॉलबैक की प्रतीक्षा करता है। दोनों मामलों में, आने वाला पेलोड पार्स किया जाता है और डाउनस्ट्रीम ब्लॉक के लिए वेरिएबल के रूप में उपलब्ध कराया जाता है। आप वैकल्पिक रूप से Webhook Response Block का उपयोग करके कॉलर को एक कस्टम HTTP प्रतिक्रिया वापस भेज सकते हैं।

यह API Block का विपरीत है। API Block आउटबाउंड अनुरोध भेजता है। Webhook Block इनबाउंड अनुरोधों के लिए सुनता है। विशिष्ट उपयोग के मामलों में एक बाहरी घटना से एक नया कन्वर्सेशन शुरू करना (एक फ़ॉर्म सबमिशन, एक CRM रिकॉर्ड निर्माण, एक iPaaS ट्रिगर जैसे n8n या Zapier), एक भुगतान गेटवे कॉलबैक की प्रतीक्षा करना, एक तृतीय-पक्ष SMS प्रदाता से OTP डिलीवरी पुष्टि प्राप्त करना, एक लंबे समय तक चलने वाला बैकएंड जॉब पूरा होने पर सूचित होना, या एक बाहरी ऐप से async अपडेट स्वीकार करना शामिल है।

Webhook Block बनाम API Block

पहलू	API Block	Webhook Block
दिशा	आउटबाउंड (बॉट API को कॉल करता है)	इनबाउंड (बाहरी सिस्टम बॉट को कॉल करता है)
ट्रिगर	फ़्लो ब्लॉक तक पहुंचने पर स्वचालित	बाहरी HTTP POST फ़्लो शुरू या फिर से शुरू करता है
स्थान	केवल mid-flow	पहला ब्लॉक या mid-flow
प्रतीक्षा व्यवहार	सिंक्रोनस, 30 सेकंड टाइमआउट	आगमन पर फ़्लो शुरू करता है, या कॉल आने तक फ़्लो रोकता है
विशिष्ट उपयोग	डेटा देखना, अपडेट पुश करना	बाहरी घटनाओं से कन्वर्सेशन शुरू करना, async कॉलबैक की प्रतीक्षा करना
प्रतिक्रिया हैंडलिंग	प्रतिक्रिया बॉडी को वेरिएबल में पार्स करता है	आने वाला पेलोड वेरिएबल बन जाता है

इसे कहां खोजें

1. Studio में अपना चैटबॉट खोलें
2. बाएं साइडबार से Webhook ब्लॉक को कैनवास पर ड्रैग करें
3. इसे अपने फ़्लो के पहले ब्लॉक के रूप में रखें (एक बाहरी घटना से एक कन्वर्सेशन शुरू करने के लिए) या इसे किसी भी पिछले ब्लॉक के बाद कनेक्ट करें (mid-flow एक कॉलबैक के लिए रुकने और प्रतीक्षा करने के लिए)
4. इसे कॉन्फ़िगर करने के लिए ब्लॉक पर डबल-क्लिक करें

कॉलर को एक कस्टम HTTP प्रतिक्रिया वापस भेजने के लिए, Webhook ब्लॉक के तुरंत बाद एक Webhook Response ब्लॉक जोड़ें।

पहले ब्लॉक के रूप में Webhook

जब Webhook ब्लॉक फ़्लो का पहला ब्लॉक होता है, तो अभी तक कोई सक्रिय कन्वर्सेशन नहीं होता। बाहरी POST कन्वर्सेशन बनाता है, पेलोड को वेरिएबल में पार्स करता है, और फ़्लो को बिल्कुल शुरुआत से शुरू करता है। यह उपयोग करने का पैटर्न है जब:

• आपके CRM में एक नया लीड बनाया जाता है और आप चाहते हैं कि बॉट संपर्क करे
• आपकी वेबसाइट पर एक फ़ॉर्म सबमिट किया जाता है और आप चाहते हैं कि बॉट फॉलो अप करे
• एक n8n, Zapier, या Make वर्कफ़्लो एक नया चैट सत्र ट्रिगर करता है
• एक बैकएंड घटना (ऑर्डर रखा गया, सपोर्ट टिकट खोला गया) को एक बॉट कन्वर्सेशन शुरू करना चाहिए

Mid-Flow Webhook

जब Webhook ब्लॉक किसी अन्य ब्लॉक के बाद रखा जाता है, तो फ़्लो उस बिंदु पर तब तक रुक जाता है जब तक बाहरी POST नहीं आता। यह उपयोग करने का पैटर्न है जब आपको एक बाहरी सिस्टम को सौंपने, इसकी async प्रतिक्रिया की प्रतीक्षा करने, और फिर इसके द्वारा लौटाए गए के आधार पर फ़्लो जारी रखने की आवश्यकता होती है।

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

पहले-ब्लॉक मोड

External system POSTs to webhook URL
                 │
                 ▼
   New conversation is created
                 │
                 ▼
   Payload parsed into variables
                 │
                 ▼
   Flow starts from the next block
                 │
                 ▼
   Webhook Response sent (optional)

Mid-Flow मोड

Bot flow runs ──▶ Reaches Webhook Block ──▶ Flow pauses
                                                  │
                             External system POSTs to webhook URL
                                                  │
                                                  ▼
                            Payload parsed into variables
                                                  │
                                                  ▼
                     Webhook Response sent (optional)
                                                  │
                                                  ▼
                     Flow continues to next block

mid-flow मोड में, बॉट रुकने पर वर्तमान ब्लॉक स्थिति संग्रहीत करता है। जब बाहरी POST वेबहुक URL पर आता है, तो सिस्टम इसे रुके हुए कन्वर्सेशन से मिलाता है, उस ब्लॉक से फिर से शुरू करता है, और डाउनस्ट्रीम जारी रखता है।

कॉन्फ़िगरेशन

चरण 1: फ़्लो में Webhook Block रखें

ब्लॉक को कैनवास पर उस बिंदु पर ड्रैग करें जहां फ़्लो को एक बाहरी घटना से शुरू होना चाहिए या उसकी प्रतीक्षा करनी चाहिए। उदाहरण के लिए:

• पहले ब्लॉक के रूप में, एक CRM, फ़ॉर्म, या iPaaS टूल को एक नया चैट कन्वर्सेशन शुरू करने देने के लिए
• भुगतान विवरण कैप्चर करने के बाद, भुगतान गेटवे पुष्टि की प्रतीक्षा करने के लिए
• एक API ब्लॉक के माध्यम से एक बैकएंड जॉब ट्रिगर करने के बाद, जॉब-पूर्ण सूचना की प्रतीक्षा करने के लिए

चरण 2: Webhook URL कॉपी करें

प्रत्येक Webhook ब्लॉक ब्लॉक कॉन्फ़िगरेशन में दिखाया गया एक अद्वितीय URL उजागर करता है। प्रारूप है:

https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/

इस URL को बाहरी सिस्टम को इसके POST अनुरोध के गंतव्य के रूप में पास करें। iPaaS टूल (n8n, Zapier, Make) के लिए आप इसे HTTP चरण में पेस्ट करते हैं। CRM और फ़ॉर्म बिल्डर के लिए, इसे उनके डैशबोर्ड में एक आउटगोइंग वेबहुक के रूप में कॉन्फ़िगर करें। भुगतान गेटवे और async बैकएंड के लिए, जब आप काम शुरू करते हैं तो इसे कॉलबैक URL के रूप में सेट करें।

चरण 3: कॉलर को प्रमाणित करें

वेबहुक URL Authorization हेडर में एक Bearer टोकन स्वीकार करता है। ब्लॉक कॉन्फ़िगरेशन में दिखाए गए टोकन का उपयोग करें ताकि वेबहुक केवल उन सिस्टमों से कॉल स्वीकार करे जिन पर आप भरोसा करते हैं।

curl -X POST https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  --data '{
    "type": "Conversation",
    "channel": "",
    "account_alias": "",
    "reference_id": "",
    "data": {
      "name": ""
    }
  }'

पेलोड आकार

फ़ील्ड	उद्देश्य
type	घटना प्रकार, आमतौर पर एक चैट शुरू या फिर से शुरू करने के लिए Conversation
channel	वह चैनल जिसका कन्वर्सेशन को उपयोग करना चाहिए (जैसे whatsapp, website)। डिफ़ॉल्ट उपयोग करने के लिए खाली छोड़ें
account_alias	टीम उपनाम जब बॉट कई खातों में साझा किया जाता है
reference_id	बाहरी पहचानकर्ता जिसका उपयोग आप कन्वर्सेशन को अपने सिस्टम में एक रिकॉर्ड से वापस जोड़ने के लिए कर सकते हैं
data	किसी भी फ़ील्ड वाला ऑब्जेक्ट जिसे आप वेरिएबल के रूप में पास करना चाहते हैं (जैसे name, email, phone, कस्टम फ़ील्ड)

चरण 4: आने वाले पेलोड फ़ील्ड को संदर्भित करें

जब POST आता है, तो data ऑब्जेक्ट पार्स किया जाता है और प्रत्येक फ़ील्ड सभी डाउनस्ट्रीम ब्लॉक के लिए उपलब्ध एक वेरिएबल बन जाता है।

इस तरह के पेलोड के लिए:

{
  "type": "Conversation",
  "channel": "whatsapp",
  "reference_id": "ORDER-9981",
  "data": {
    "name": "Priya",
    "phone": "+919000000000",
    "order_id": "ORDER-9981",
    "customer": {
      "email": "priya@example.com"
    }
  }
}

आप संदर्भित कर सकते हैं:

• Priya के लिए {name}
• +919000000000 के लिए {phone}
• ORDER-9981 के लिए {order_id}
• नेस्टेड फ़ील्ड के लिए {customer.email}
• शीर्ष-स्तरीय मेटाडेटा के लिए {reference_id}

चरण 5: सबमिट करें और सहेजें

ब्लॉक मोडल में Submit पर क्लिक करें, फिर शीर्ष बार में Save Changes का उपयोग करके फ़्लो सहेजें।

Webhook Response Block

जब कॉलर एक विशिष्ट HTTP प्रतिक्रिया की अपेक्षा करता है तो Webhook ब्लॉक को एक Webhook Response Block के साथ जोड़ें। प्रतिक्रिया ब्लॉक के बिना, बॉट {"status":"success"} के साथ एक डिफ़ॉल्ट 200 OK लौटाता है।

Webhook Response Block आपको स्थिति कोड (जैसे 201, 400, 500), सामग्री प्रकार (application/json, application/xml, text/plain, text/html), और कॉलर को वापस भेजी गई प्रतिक्रिया बॉडी को अनुकूलित करने देता है। आप {variable_name} सिंटैक्स के साथ फ़्लो वेरिएबल सम्मिलित कर सकते हैं।

सामान्य पैटर्न:

• iPaaS टूल के लिए नई {conversation_id} के साथ 201 Created लौटाएं
• पेलोड अमान्य होने पर एक त्रुटि फ़ील्ड के साथ 400 लौटाएं
• SMS डिलीवरी कॉलबैक के लिए text/plain OK लौटाएं
• लीगेसी SOAP एकीकरण के लिए XML लौटाएं

कॉन्फ़िगरेशन विकल्प, उदाहरण, और समस्या निवारण के लिए पूर्ण Webhook Response Block दस्तावेज़ देखें।

सर्वोत्तम अभ्यास

• हमेशा आने वाले पेलोड को सत्यापित करें। आगे बढ़ने से पहले status == "success" जैसे फ़ील्ड को सत्यापित करने के लिए Webhook ब्लॉक के बाद एक Condition ब्लॉक का उपयोग करें
• जब कॉलर (भुगतान गेटवे, SMS प्रदाता, आदि) एक विशिष्ट पावती प्रारूप की अपेक्षा करता है तो Webhook Response ब्लॉक का उपयोग करें। इसके बिना, कॉलर को एक सामान्य 200 OK मिलता है
• कहीं और एक सार्थक टाइमआउट सेट करें। Webhook ब्लॉक स्वयं टाइम आउट नहीं होता, इसलिए अनिश्चित काल तक रुके रहने वाले फ़्लो से बचने के लिए इसे Inactivity Timeout के साथ संयोजित करें
• वेबहुक URL को सुरक्षित करें। URL में टोकन प्रति कन्वर्सेशन अद्वितीय है। URL को सार्वजनिक रूप से उजागर न करें या इसे उन सिस्टमों में लॉग न करें जिन्हें उपयोगकर्ता पढ़ सकता है
• विफलता मामले को संभालें। आने वाले पेलोड के आधार पर फ़्लो को शाखा बनाएं। यदि बाहरी घटना विफलता का संकेत देती है, तो एक रिकवरी संदेश भेजें या एक एजेंट को रूट करें

सामान्य उपयोग के मामले

CRM Lead एक कन्वर्सेशन बनाता है (पहला-ब्लॉक)

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

1. Webhook Block (पहला ब्लॉक): CRM phone, name, source के साथ लीड पेलोड POST करता है
2. Message Block: Hi {name}, thanks for your interest!
3. Question Block: योग्यता प्रश्न पूछें
4. API Block: योग्य डेटा को CRM में वापस पुश करें

n8n या Zapier Trigger (पहला-ब्लॉक)

एक ऑटोमेशन टूल एक विशिष्ट घटना होने पर एक वेबहुक फायर करता है (नया Shopify ऑर्डर, Typeform सबमिशन, आदि), और बॉट ग्राहक के साथ फॉलो अप करता है।

1. Webhook Block (पहला ब्लॉक): n8n {"phone":"...", "order_id":"..."} POST करता है
2. Message Block: Your order {order_id} has shipped!

भुगतान गेटवे कॉलबैक

उपयोगकर्ता भुगतान शुरू करता है, बॉट उन्हें एक भुगतान पेज पर भेजता है, फिर गेटवे द्वारा परिणाम POST करने की प्रतीक्षा करता है।

1. API Block: भुगतान सत्र बनाएं, payment_url संग्रहीत करें
2. Message Block: उपयोगकर्ता को payment_url भेजें
3. Webhook Block: फ़्लो रोकें, वेबहुक URL को गेटवे को कॉलबैक के रूप में पास करें
4. Condition Block: {status} == "success" पर शाखा बनाएं
5. Webhook Response Block: गेटवे को {"received":true} लौटाएं

Async Job सूचना

बॉट एक लंबे समय तक चलने वाला रिपोर्ट जनरेशन जॉब ट्रिगर करता है, पूरा होने की प्रतीक्षा करता है, फिर उपयोगकर्ता को रिपोर्ट लिंक भेजता है।

1. API Block: जॉब सबमिट करें, job_id संग्रहीत करें, कॉलबैक के रूप में वेबहुक URL शामिल करें
2. Message Block: "Generating your report, this may take a minute..."
3. Webhook Block: जॉब-पूर्ण कॉलबैक की प्रतीक्षा करें
4. Message Block: Your report is ready: {report_url}

तृतीय-पक्ष OTP डिलीवरी स्थिति

बॉट एक बाहरी SMS प्रदाता के माध्यम से एक OTP भेजता है जो डिलीवरी की पुष्टि करने के लिए वेबहुक का उपयोग करता है।

1. API Block: OTP भेजना ट्रिगर करें, वेबहुक URL पास करें
2. Webhook Block: डिलीवरी स्थिति की प्रतीक्षा करें
3. Condition Block: {delivery_status} पर शाखा बनाएं
4. Message Block: OTP कोड के लिए पूछें या डिलीवरी विफलता के लिए क्षमा मांगें

बाहरी फ़ॉर्म सबमिशन

एक अलग वेब ऐप अतिरिक्त जानकारी एकत्र करता है और उपयोगकर्ता के समाप्त होने पर इसे बॉट को POST करता है।

1. Message Block: उपयोगकर्ता को फ़ॉर्म URL भेजें
2. Webhook Block: फ़ॉर्म सबमिशन की प्रतीक्षा करें
3. Message Block: Thanks, we received your {form_field}

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

फ़्लो Webhook ब्लॉक पर अटका हुआ है (mid-flow)

1. पुष्टि करें कि बाहरी सिस्टम ने वास्तव में वेबहुक URL पर POST किया। उनके डिलीवरी लॉग जांचें
2. सत्यापित करें कि URL बाहरी सिस्टम से पहुंच योग्य है (फ़ायरवॉल या IP allowlist द्वारा अवरुद्ध नहीं)
3. सुनिश्चित करें कि URL में पूरा पथ और ट्रेलिंग टोकन शामिल है
4. कॉलबैक कभी प्राप्त न करने वाले कन्वर्सेशन को स्वतः-बंद करने के लिए Inactivity Timeout के साथ संयोजित करें

पहला-ब्लॉक वेबहुक एक कन्वर्सेशन शुरू नहीं कर रहा

1. पुष्टि करें कि Webhook ब्लॉक फ़्लो में बिल्कुल पहला ब्लॉक है (कोई अन्य ब्लॉक इसमें कनेक्ट नहीं होता)
2. सत्यापित करें कि पेलोड में एक प्राप्तकर्ता पहचानकर्ता (फ़ोन, ईमेल, या विज़िटर ID) शामिल है जिसका उपयोग बॉट कन्वर्सेशन बनाने के लिए कर सकता है
3. जांचें कि बॉट प्रकाशित है और चैनल (WhatsApp, वेबसाइट विजेट, आदि) कनेक्ट है
4. कॉलर को लौटाई गई प्रतिक्रिया स्थिति का निरीक्षण करें। एक 4xx इंगित करता है कि पेलोड अस्वीकृत किया गया था

आने वाले पेलोड फ़ील्ड डाउनस्ट्रीम ब्लॉक में खाली हैं

1. पुष्टि करें कि आने वाले POST का Content-Type application/json या एक समर्थित फ़ॉर्म प्रकार है
2. पेलोड में सटीक फ़ील्ड नाम जांचें। वेरिएबल नाम केस-संवेदनशील होते हैं
3. नेस्टेड फ़ील्ड के लिए, डॉट नोटेशन का उपयोग करें: {customer.email}, {customer_email} नहीं
4. यह देखने के लिए कि वास्तव में क्या प्राप्त हुआ था, कन्वर्सेशन लॉग में कच्चे आने वाले पेलोड का निरीक्षण करें

कॉलर को मेरी कस्टम प्रतिक्रिया के बजाय एक सामान्य 200 OK मिलता है

1. सुनिश्चित करें कि आपने Webhook ब्लॉक के बाद एक Webhook Response ब्लॉक जोड़ा
2. सत्यापित करें कि प्रतिक्रिया ब्लॉक फ़्लो ग्राफ़ में पहुंच योग्य है। एक Condition ब्लॉक इसके चारों ओर रूट कर रहा हो सकता है
3. दोबारा जांचें कि Submit बटन पर क्लिक किया गया था और फ़्लो सहेजा गया था

बाहरी सिस्टम वेबहुक प्रतिक्रिया को अस्वीकार करता है

1. पुष्टि करें कि Content-Type उससे मेल खाता है जो कॉलर अपेक्षा करता है (उदाहरण के लिए, application/json बनाम text/plain)
2. सत्यापित करें कि प्रतिक्रिया बॉडी सुगठित है। एक अनबंद JSON ऑब्जेक्ट सख्त कॉलर को पुनः प्रयास करने का कारण बनेगा
3. HTTP स्थिति कोड जांचें। कुछ कॉलर केवल 200 स्वीकार करते हैं, 201 या 202 नहीं

एक ही कन्वर्सेशन के लिए कई POST आते हैं

कुछ बाहरी सिस्टम वेबहुक का पुनः प्रयास करते हैं यदि उन्हें लगता है कि पहली डिलीवरी विफल हुई। वेबहुक URL प्रति कन्वर्सेशन idempotent है, इसलिए केवल पहला वैध POST फ़्लो फिर से शुरू करता है। बाद के POST फ़्लो को फिर से आगे बढ़ाए बिना कॉन्फ़िगर की गई प्रतिक्रिया प्राप्त करते हैं।

अगले चरण

• Webhook Response Block - कॉलर को कस्टम HTTP प्रतिक्रियाएं वापस भेजें
• API Block - फ़्लो से बाहरी API कॉल करें
• Inactivity Timeout - बहुत लंबे समय तक रुके रहने वाले कन्वर्सेशन को स्वतः-बंद करें
• Conversation End Block - एक रीस्टार्ट बटन के साथ कन्वर्सेशन को मैन्युअल रूप से समाप्त करें
• Studio अवलोकन - सभी ब्लॉक प्रकार और फ़्लो बिल्डर सुविधाओं का अन्वेषण करें