वेबहुक क्या है?

जब Bird आपके एंडपॉइंट को कॉल करता है, तो काम शुरू होने से पहले रिसीवर को इवेंट सुरक्षित रखना होता है। वेबहुक एक HTTP अनुरोध है जिसे कोई सिस्टम कुछ होने पर आपके ऐप्लिकेशन को भेजता है। भेजने वाला POST पर हस्ताक्षर करके उसे आपके रजिस्टर किए गए URL पर भेजता है। इवेंट कब स्थायी रूप से स्वीकार हुआ, यह आपका रिसीवर तय करता है।

वेबहुक किसी API की पोलिंग से कैसे अलग है?

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

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

वेबहुक अनुरोध कैसा दिखता है?

वेबहुक अनुरोध हेडर और JSON इवेंट एनवेलप वाला एक HTTP POST होता है। Bird के ईमेल डिलीवरी इवेंट में type, एक इवेंट timestamp और प्रकार के अनुसार data होते हैं:

{
  "type": "email.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient_id": "er_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "recipient": "user@example.com",
    "recipient_role": "to",
    "tags": [{ "name": "category", "value": "welcome" }],
    "metadata": { "order_id": "ord_123" },
    "broadcast_id": null
  }
}

मैसेज ID data.email_id है। डिलीवरी की पहचान webhook-id हेडर है, जो Bird के उस इवेंट को फिर से प्रयास करने या रीप्ले करने पर भी वही रहता है। बॉडी का timestamp दर्ज करता है कि इवेंट कब हुआ। webhook-timestamp हेडर इस डिलीवरी प्रयास का समय दर्ज करता है, इसलिए दोनों टाइमस्टैम्प अलग-अलग सवालों का जवाब देते हैं। इवेंट-विशिष्ट पेलोड के लिए ईमेल इवेंट फ़ील्ड देखें।

वेबहुक हस्ताक्षर को कैसे सत्यापित करें?

अनुरोध के मूल बाइट सुरक्षित रखें और इवेंट को पार्स या संग्रहीत करने से पहले हस्ताक्षर सत्यापित करें। Bird का SDK webhook-id, webhook-timestamp और webhook-signature हेडर जांचता है। यह आपके लिए टाइमस्टैम्प की सहनशीलता सीमा भी लागू करता है। दूसरा सत्यापनकर्ता लिखने के बजाय हस्ताक्षर गाइड का उपयोग करें।

अगर आपको साइनिंग इनपुट समझना है, तो Bird {webhook-id}.{webhook-timestamp}.{raw request body} का उपयोग करता है। एंडपॉइंट सीक्रेट whsec_ से शुरू होता है। HMAC-SHA256 की गणना करने से पहले यह प्रीफ़िक्स हटाएँ और बाकी हिस्से को base64-डीकोड करें। सीक्रेट रोटेशन के दौरान सिग्नेचर हेडर में स्पेस से अलग किए गए कई v1, मान हो सकते हैं, इसलिए सक्रिय सीक्रेट में से किसी से मेल खाने वाला मान स्वीकार करें।

गलत ढाँचे वाले, बिना प्रमाणीकरण वाले या पुराने अनुरोधों को स्टोर करने से पहले ही अस्वीकार करें। पहले JSON को पार्स करने से व्हाइटस्पेस या कुंजियों का क्रम बदल सकता है, जिससे बाइट्स साइन किए गए संदेश से मेल नहीं खाते।

वेबहुक को कैसे स्टोर करें और उसकी प्राप्ति की पुष्टि कैसे करें?

सफलता लौटाने से पहले सत्यापित इवेंट और उससे जुड़े काम को टिकाऊ रूप से सहेजें। इवेंट को webhook-id कुंजी के साथ डालें। नए इवेंट के लिए वर्क आइटम डालें। दोनों को एक ही ट्रांज़ैक्शन में कमिट करें, या इसके बराबर टिकाऊ इनबॉक्स और आउटबॉक्स डिज़ाइन का उपयोग करें।

read raw bytes and headers
verify the signature and timestamp with the Bird SDK
begin a durable transaction
  insert the inbox event keyed by webhook-id, unless it already exists
  insert a durable work item for a new event
commit the transaction
return 204
worker processes the persisted event idempotently

जो डुप्लिकेट पहले से टिकाऊ रूप से स्टोर है, उसे नया काम बनाए बिना 204 लौटाया जा सकता है। टिकाऊ कमिट विफल होने पर गैर-2xx लौटाएँ, ताकि Bird डिलीवरी के लिए फिर से प्रयास करे। सफलता लौटाने के बाद, Bird से इवेंट दोबारा भेजे जाने की अपेक्षा न करें, बल्कि अपने टिकाऊ रिकॉर्ड से लोकल वर्कर के लिए फिर से प्रयास करें।

यह क्रम Bird के कम से कम एक बार डिलीवरी के नियमों के लिए एक एप्लिकेशन डिज़ाइन है। यह कोई ऐसी कतार नहीं है जिसे Bird आपके लिए चलाता हो। डुप्लिकेट और आइडेम्पोटेंसी गाइड में डुप्लिकेट हटाने के निर्णय का अधिक विस्तार से वर्णन है।

वेबहुक के लिए फिर से प्रयास और रीप्ले कैसे काम करते हैं?

Bird सामान्य डिलीवरी को प्रतिक्रिया पाने के लिए 15 सेकंड देता है। कोई भी 2xx स्टेटस सफल माना जाता है। गैर-2xx स्टेटस, रीडायरेक्ट या टाइमआउट विफल माने जाते हैं और फिर से प्रयास करने के शेड्यूल का पालन करते हैं।

शुरुआती अनुरोध सहित इस क्रम में 8 प्रयास होते हैं। हर विलंब पर प्लस या माइनस 20% जिटर लागू होता है। 429 या कनेक्शन टाइमआउट होने पर मूल विलंब 60 सेकंड हो जाता है। जिटर से पहले, एक धनात्मक Retry-After मान को उस मूल विलंब और उसके दोगुने के बीच सीमित किया जाता है, इसलिए तालिका सटीक पहुँचने का समय नहीं, बल्कि मूल विलंब बताती है। विफलता की प्रक्रिया के लिए विफल webhook के लिए फिर से प्रयास कैसे होता है देखें।

डिलीवरी किसी तय क्रम में नहीं आतीं, इसलिए केवल पहुँचने के क्रम के आधार पर एप्लिकेशन की मौजूदा स्थिति अपडेट न करें। जब इवेंट क्रम से बाहर आ सकते हों, तो इवेंट के timestamp और अपने रिसोर्स की स्थिति का उपयोग करें।

कोई डिलीवरी छूट जाए, तो webhook प्रयास जाँचें। रिसीवर ठीक करें। फिर एक webhook रीप्ले बनाएँ। Bird उन डिलीवरी को छोड़ देता है जो एंडपॉइंट को पहले ही सफलतापूर्वक मिल चुकी हैं। रीप्ले मूल webhook-id का ही उपयोग करता है, इसलिए वही डीडुप्लिकेशन कुंजी उसे भी सुरक्षित रखती है।

webhook की बुनियादी बातें समझने के बाद आपको क्या कनेक्ट करना चाहिए?

एक एंडपॉइंट बनाएँ। उसकी हस्ताक्षरित डिलीवरी को सत्यापित करें और टिकाऊ रूप से स्वीकार करें। डिलीवरी प्रयास जाँचें। विफल डिलीवरी को रीप्ले करें। इसके बाद, डिलीवरी गँवाए बिना नया साइनिंग सीक्रेट लागू करने के लिए सीक्रेट रोटेशन का उपयोग करें।