Webhook क्या है?

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

Webhook, API की पोलिंग से कैसे अलग है?

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

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

Webhook रिक्वेस्ट कैसी दिखती है?

Webhook रिक्वेस्ट एक HTTP POST होती है जिसमें हेडर और एक JSON इवेंट एन्वेलप होता है। 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 हेडर इस डिलीवरी प्रयास का समय दर्ज करता है, इसलिए दोनों टाइमस्टैम्प अलग-अलग सवालों का जवाब देते हैं। इवेंट-विशिष्ट पेलोड के लिए ईमेल इवेंट फ़ील्ड देखें।

Webhook सिग्नेचर को कैसे सत्यापित करें?

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

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

विकृत, अप्रमाणित, या पुरानी रिक्वेस्ट को स्टोरेज से पहले अस्वीकार करें। पहले JSON पार्स करने से व्हाइटस्पेस या की ऑर्डर बदल सकता है और बाइट्स साइन किए गए मैसेज से मेल नहीं खाते।

Webhook को कैसे स्टोर और एकनॉलेज करें?

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

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 मिल सकता है। जब ड्यूरेबल कमिट विफल हो तो non-2xx लौटाएँ, ताकि Bird डिलीवरी फिर से प्रयास करे। एक बार सफलता लौटाने के बाद, Bird से इवेंट दोबारा भेजने की अपेक्षा करने के बजाय अपने ड्यूरेबल रिकॉर्ड से लोकल वर्कर को फिर से प्रयास करें।

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

Webhook के फिर से प्रयास और रीप्ले कैसे काम करते हैं?

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

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

डिलीवरी अनऑर्डर्ड होती हैं, इसलिए केवल आगमन क्रम से वर्तमान ऐप्लिकेशन स्टेट अपडेट न करें। जब इवेंट क्रम से बाहर आ सकते हों तो इवेंट timestamp और अपने रिसोर्स स्टेट का उपयोग करें।

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

Webhook की बुनियादी बातें सीखने के बाद आपको आगे क्या जोड़ना चाहिए?

एक एंडपॉइंट बनाएँ। इसकी साइन की गई डिलीवरी को सत्यापित करें और स्थायी रूप से स्वीकार करें। डिलीवरी प्रयास की जाँच करें। छूटे हुए इवेंट रीप्ले करें। फिर डिलीवरी खोए बिना नया साइनिंग सीक्रेट डिप्लॉय करने के लिए सीक्रेट रोटेशन का उपयोग करें।