वेबहुक डिलीवरी गारंटी

वेबहूक HTTP (S) पर अतुल्यकालिक सिस्टम-टू-सब्सक्राइबर सूचनाएं हैं। नेटवर्क अविश्वसनीय है: प्रतिक्रियाएं खो जाती हैं, पैकेट डुप्लिकेट में या क्रम से बाहर आते हैं। इसलिए, डिलीवरी गारंटी "टीसीपी पर" नहीं बनाई गई है, लेकिन वेबहुक प्रोटोकॉल और डोमेन पहचान के स्तर पर है।

मुख्य लक्ष्य: कुंजी (जहां आवश्यक हो) द्वारा आदेश के साथ कम से कम एक बार डिलीवरी प्रदान करना, पहचान प्रसंस्करण के लिए ग्राहक सामग्री और बहाली के लिए एक सामंजस्य उपकरण देना।

1) वारंटी का स्तर

सर्वश्रेष्ठ प्रयास - एक बार का प्रयास, बिना रेट्रास के। केवल "महत्वहीन" घटनाओं के लिए स्वीकार्य।

कम से कम-एक बार (अनुशंसित) - डुप्लिकेट और आउट-ऑफ-ऑर्डर संभव है, लेकिन घटना को वितरित किया जाएगा बशर्ते कि ग्राहक एक उचित समय के भीतर उपलब्ध हो।

प्रभावी रूप से-बिल्कुल-एक बार (प्रभाव स्तर पर) - ग्राहक/प्रेषक पक्ष में पहचान और डेडअप भंडारण के संयोजन द्वारा प्राप्त किया गया। "बिल्कुल एक बार" HTTP परिवहन संभव नहीं है।

2) वेबहुक अनुबंध: न्यूनतम आवश्यक

X-Webhook-Id: 5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21  # глобальный ID события
X-Delivery-Attempt: 3                 # номер попытки
X-Event-Type: payment.authorized.v1          # тип/версия
X-Event-Time: 2025-10-31T12:34:56Z          # ISO8601
X-Partition-Key: psp_tx_987654            # ключ порядка
X-Seq: 418                      # монотонный номер по ключу
X-Signature-Alg: HMAC-SHA256
X-Signature: t=1730378096,v1=hex(hmac(secret, t        body))
Content-Type: application/json

json
{
"id": "5d1e6a1b-4f7d-4a3d-8b3a-6c2b2f0f3f21",
"type": "payment.authorized.v1",
"occurred_at": "2025-10-31T12:34:56Z",
"partition_key": "psp_tx_987654",
"sequence": 418,
"data": {
"payment_id": "psp_tx_987654",
"amount": "10.00",
"currency": "EUR",
"status": "AUTHORIZED"
},
"schema_version": 1
}

प्राप्तकर्ता के लिए आवश्यकता: हस्ताक्षर को बफरिंग और मान्य करने के बाद जल्दी से '2xx' का जवाब दें, और अतुल्यकालिक रूप से व्यवसाय प्रसंस्करण करें।

3) आदेश और कारण

कुंजी क्रम: गारंटी "केवल एक 'विभाजन _ कुंजी' (उदा। 'प्लेयर _ आईडी', 'वॉलेट _ आईडी', 'psp _ tx _ id')।

वैश्विक व्यवस्था की गारंटी नहीं है।

प्रेषक पक्ष में कुंजी (एक उपभोक्ता/शार्डिंग) द्वारा क्रमबद्धता के साथ एक कतार है, प्राप्तकर्ता पक्ष में '(स्रोत, event_id)' के साथ एक इनबॉक्स है और वैकल्पिक रूप से लापता 'seq' की प्रतीक्रतीक्षा कर रहा है।

यदि अंतराल महत्वपूर्ण हैं - पुल-एपीआई 'गेट/इवेंट प्रदान करें? "कैच अप और परामर्श" के लिए = चेकपॉइंट के बाद।

4) पहचान और कमी

प्रत्येक वेबहुक में एक स्थिर 'एक्स-वेबहुक-आईडी' होता है।

प्राप्तकर्ता 'इनबॉक्स (event_id)': पीके - 'स्रोत + event_id'; दोहराता है - नो-ऑप।

साइड इफेक्ट्स (डेटाबेस/वॉलेट पर लिखना) केवल एक बार किया जाता है जब घटना को पहली बार "देखा" जाता है।

प्रभाव वाले कमांड के लिए, retray विंडो की अवधि के लिए Idempotency-Key और परिणाम कैश का उपयोग करें।

5) रेट्राई, बैकऑफ और विंडो

• '5xx/timeout/connection error/409-Conflict (रिट्रीबल )/429' पर पुनः प्राप्त करें।
• '4xx' पर '409/423/429' को छोड़ कर (और केवल सुसंगत शब्दार्थ के साथ) वापस न लें।
• घातीय बैकऑफ + फुल जिटर: 0। 5s, 1s, 2s, 4s, 8s,... 'अधिकतम = 10-15 मिनट' तक; टीटीएल पुनः प्राप्त विंडो: उदाहरण के लिए, 72 घंटे।
• प्राप्तकर्ता से 'रीट्री-आफ्टर' का सम्मान करें।
• एक सामान्य समय सीमा है: "घटना को वितरित नहीं करने के रूप में पहचानें" और इसे डीएलक्यू में स्थानांतरित करें।

yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]

6) DLQ и redrive

DLQ - पूर्ण मेटा जानकारी (पेलोड, हेडर, त्रुटियां, प्रयास, हैश) के साथ जहरीली या टीटीएल-समाप्त घटनाओं का "कब्रिस्तान"।

वैकल्पिक समापन बिंदु/गुप्त संपादन के साथ पुनर्वितरण (बिंदु पुन: वितरण) के लिए वेब कंसोल/एपीआई।

दर-सीमित redrive और बैच-रीड्राइव प्राथमिकता।

7) सुरक्षा

mTLS (यदि संभव हो) या TLS 1। 2+.

1. शीर्षिका से 't' (timestamp) निकालें, स्लाइडिंग विंडो की जाँच करें (उदाहरण के लिए, '5 मिनट).

8) कोटा, दर सीमा और इक्विटी

फेयर-क्यू प्रति किरायेदार/ग्राहक: ताकि एक ग्राहक/किरायेदार समग्र पूल स्कोर न करे।

निवर्तमान यातायात और प्रति-समापन बिंदु के लिए कोटा और फट सीमा।

'429' की प्रतिक्रिया: 'रेट्री-आफ्टर', ट्रोल स्ट्रीम का सम्मान; दीर्घकालिक सीमित के लिए - नीचा (केवल महत्वपूर्ण घटना प्रकार भेजना)।

9) सदस्यता जीवनचक्र

रजिस्टर/सत्यापन: POST समापन बिंदु → चुनौती/प्रतिक्रिया या बैंड से बाहर की पुष्टि।

लीज (वैकल्पिक): हस्ताक्षर 'वैध _ टू' तक वैध है; लम्बा - स्पष्ट।

गुप्त घुमाव: 'वर्तमान _ गुप्त', 'अगला _ गुप्त' с 'स्विच _ at'।

टेस्ट पिंग: मुख्य विषयों को चालू करने से पहले मार्ग का परीक्षण करने के लिए एक कृत्रिम घटना।

स्वास्थ्य नमूने: आवधिक HEAD/GET विलंबता और TLS प्रोफाइल जांच के साथ।

10) योजनाओं का विकास (घटना संस्करण)

संस्करण घटना प्रकार: 'भुगतान। अधिकृत। v1 '→'... v2 '।

एवोल्यूशन - एडिटिव (नया फ़ील्ड - MINTER API संस्करण), एक नया प्रकार।

स्कीमा रजिस्टर (JSON-Schema/Avro/Protobuf) + जमा करने से पहले स्वचालित सत्यापन।

'एक्स-इवेंट-टाइप' हेडर और शरीर में 'स्कीमा _ संस्करण' दोनों आवश्यक हैं।

11) अवलोकन और एसएलओ

• 'डेलीवेरीज़ _ टोटल', '2xx/4xx/5xx _ रेट', 'टाइमआउट _ रेट', 'सिग्नेचर _ फेल _ रेट'।
• 'attempts _ avg', 'p50/p95/p99 _ delivency _ latency _ ms' (2xx पर प्रकाशित करें)।
• 'dedup _ rate', 'out _ of _ of _ ord _ rate', 'dlq _ rate', 'redrive _ amety _ rate'।
• 'queue _ depth', 'सबसे पुराना _ in _ cowe _ ms', 'थ्रॉटल _ events'।

• प्रसव का हिस्सा ≤ 60 एस (p95) - 99। महत्वपूर्ण घटनाओं के लिए 5%
• DLQ ≤ 0। 24 घंटे में 1%
• हस्ताक्षर विफलता ≤ 0। 05%.

Логи/трейсинг: 'event _ id', 'partion _ key', 'seq', 'partision', 'tearch', 'endpoint _ id', 'schema _ version', 'trace _ id'।

12) प्रेषक संदर्भ एल्गोरिथ्म

1. ट्रांजेक्शनल आउटबॉक्स में घटना लिखें।

2. परिभाषित करें - और seq; कतार।

3. कार्यकर्ता कुंजी द्वारा लेता है, एक अनुरोध, संकेत बनाता है, टाइमआउट (कनेक्ट/रीड) के साथ भेजता है।

4. '2xx' के साथ - वितरित के रूप में पहचानें, विलंबता और seq-चौकी को ठीक करें।

5. '429/5xx/timeout' के साथ - नीति के अनुसार पीछे हटना।

6. TTL → DLQ और अलर्ट द्वारा।

13) संदर्भ प्रोसेसर (रिसीवर)

1. अनुरोध स्वीकारें, टीएलएस/प्रोटो की जाँच करें.

2. हस्ताक्षर और समय विंडो का सत्यापन।

3. फास्ट एसीके 2xx (स्थानीय इनबॉक्स/कतार में तुल्यकालिक लिखने के बाद)।

4. अतुल्यकालिक कार्यकर्ता 'इनबॉक्स' पढ़ ता है, 'इवेंट _ आईडी' (दादा) की जाँच करता है, यदि आवश्यक हो, तो 'seq' inside 'partion _ key' द्वारा आदेश।

5. प्रभाव करता है, सामंजस्य के लिए "ऑफसेट/सेक चेकपॉइंट" लिखता है।

6. त्रुटि के मामले में - स्थानीय पुनरावृत्ति; "जहरीला" कार्य - अलर्ट के साथ स्थानीय डीएलक्यू।

14) सुलह (पूल लूप)

• 'GET/घटनाएं? partition_key=...&after_seq=...&limit=...' - सभी छूटे हुए को देने के लिए।
• टोकन चेकपॉइंट: 'आफ्टर = अपारदर्शी _ टोकन' seq के बजाय।
• idempotent redelivery: वही 'event _ id', नए 't' पर एक ही हस्ताक्षर।

15) उपयोगी शीर्षक और कोड

2xx - स्वीकृत (भले ही व्यापार प्रसंस्करण बाद में हो)।

410 गया - समापन बिंदु बंद है (प्रेषक वितरण को रोकता है और सदस्यता को "संग्रहीत" के रूप में चिह्नित करता है)।

409/423 - संसाधन का अस्थायी अवरोधन retray उचित है।

429 - बहुत बार - थ्रॉटल और बैकऑफ।

400/401/403/404 - कॉन्फ़िगरेशन त्रुटि; रेट्राई बंद करो, टिकट खोलो।

16) बहु-किरायेदार और क्षेत्र

किरायेदार/समापन बिंदु पर व्यक्तिगत कतारें और सीमाएं।

डेटा रेजिडेंसी: क्षेत्र से डेटा भेजना; एंड-टू-एंड हेडर 'एक्स-टेनेंट', 'एक्स-रीजन'।

विफलताओं का अलगाव: एक ग्राहक का पतन बाकी (अलग पूल) को प्रभावित नहीं करता है।

17) परीक्षण

संविदा परीक्षण: निकायों/हस्ताक्षरों के निश्चित उदाहरण, सत्यापन जांच।

अराजकता: ड्रॉप/डुप्लिकेट, फेरबदल ऑर्डर, नेटवर्क देरी, 'आरएसटी', 'टीएलएस' त्रुटियां।

लोड: फट-तूफान, मापा p95/p99।

सुरक्षा: एंटी-रिप्ले, पुराने टाइमस्टैम्प, गलत रहस्य, रोटेशन।

DR/Repay: अलग-अलग स्टैंड में DLQ से मास रिड्राइव करें।

18) प्लेबुक (रनबुक)

1. वृद्धि 'signation _ fail _ rate'

घड़ी बहाव की जाँच करें, समाप्त 'सहिष्णुता', रहस्यों का घूर्णन; अस्थायी रूप से "दोहरे रहस्य" को सक्षम करें।

2. कतार उम्र बढ़ ने ('सबसे पुराना _ in _ cowe _ ms') है

श्रमिकों को बढ़ाएं, महत्वपूर्ण विषयों को प्राथमिकता दें, अस्थायी रूप से "शोर" प्रकारों की आवृत्ति को कम करें।

3. ग्राहक पर तूफान '429'

प्रयासों के बीच थ्रॉटलिंग और ठहराव सक्षम करें; कम महत्वपूर्ण घटना प्रकार शि

4. मास '5xx'

एक विशिष्ट समापन बिंदु के लिए सर्किट-ब्रेकर खोलें, स्विच को स्थगित करें और बैच करें; ग्राहक को संकेत।

5. DLQ पॉपुलेट करें

गैर-महत्वपूर्ण प्रकाशन बंद करें, कम आरपीएस के साथ बैच-रीड्राइव सक्षम करें, सदस्यता मालिकों को अलर्ट बढ़ाएं।

19) विशिष्ट त्रुटियां

2xx अनुक्रिया के लिए तुल्यकालिक भारी प्रक्रमण → रिट्रेज़और डुप्लिकेट।

कोई बॉडी/टाइम विंडो हस्ताक्षर नहीं → प्रतिस्थापन/रीप्ले भेद्यता।

"वैश्विक व्यवस्था" का प्रयास - अनन्त कतार ताले।

'ईवेंट _ आईडी' और 'इनबॉक्स' की अनुपस्थिति को पहचानने योग्य नहीं बनाया जा सकता.

बिना किसी झटके/सीमा के पीछे हटना → घटना तीव्रता (गड़गड़ाहट झुंड)।

सभी ग्राहकों के लिए एक एकल सामान्य पूल - "शोर" सभी को डालता है।

20) प्री-सेल चेकलिस्ट

• संविदा: 'event _ id', 'partion _ key', 'seq', 'event _ type। vN ', HMAC हस्ताक्षर और टाइमस्टैम्प।
• प्रेषक: आउटबॉक्स, कुंजी द्वारा क्रमबद्ध, बैकऑफ + जिटर, टीटीएल, डीएलक्यू और पुनर्वितरण के साथ।
• प्राप्तकर्ता: इनबॉक्स + 2xx पर त्वरित लिखें; पहचान उपचार; स्थानीय डीएलक्यू।
• सुरक्षा: टीएलएस, हस्ताक्षर, एंटी-रिप्ले, डुअल-सीक्रेट, रोटेशन।
• कोटा/सीमाएं: किरायेदार/समापन बिंदु पर निष्पक्ष-कतार, 'पुनरावृत्ति-आफ्टर' का सम्मान करें।
• एपीआई और चौकियों को सामंजस्य स्थापित करें; ग्राहकों के लिए प्रलेखन।
• ऑब्जर्वेबिलिटी: p95/threads/errors/DLQ, 'इवेंट _ आईडी' का पता लगाएं।
• घटना संस्करण और स्कीमा विकास नीति।
• हादसा प्लेबुक और वैश्विक ठहराव/defrost बटन।

निष्कर्ष

विश्वसनीय वेबहुक HTTP के शीर्ष पर एक प्रोटोकॉल है, न कि केवल "JSON के साथ POST। "एक स्पष्ट अनुबंध (आईडी, ऑर्डर की, सिग्नेचर), आइडेम्पोटेंसी, जिटर के साथ रिट्रे, निष्पक्ष कतार और अच्छी तरह से डिबग्ड प्लेबुक सबसे अच्छे मामले को एक अनुमानित और औसत दर्जे का वितरण तंत्र में बदल देते हैं। कम से कम एक बार + कुंजी क्रम + सामंजस्य बनाएं, और सिस्टम शांति से नेटवर्क से बच जाएगा, चोटियों और मानव त्रुटियों को लोड करेगा।