वेबहूक: रिप्ले और पावती

1) बेसिक डिलीवरी मॉडल

कम से कम एक बार (डिफ़ॉल्ट) - घटना को ≥1 समय दिया जाएगा। वास्तव में एक बार गारंटी रिसीवर पहचान द्वारा प्राप्त की जाती है।

पावती (ACK): प्राप्तकर्ता से केवल किसी भी 2xx (आमतौर पर 200/204) का अर्थ है सफलता। बाकी सब कुछ एक विफलता के रूप में व्याख्या की जाती है और पुनरावृत्ति की ओर जाता है

फास्ट एसीके: घटना को बदले में रखने के बाद 2xx का जवाब दें, पूर्ण व्यवसाय प्रसंस्करण के बाद नहीं।

2) घटना प्रारूप और अनिवार्य शीर्षक

नीतभार (उदाहरण)

json
{
"id": "evt_01HXYZ",
"type": "order. created",
"occurred_at": "2025-11-03T18:10:12Z",
"sequence": 128374,
"source": "orders",
"data": { "order_id": "o_123", "amount": "49. 90", "currency": "EUR" },
"schema_version": 1
}

प्रेषक शीर्षिका

'एक्स-वेबहुक-आईडी: evt_01HXYZ' - अद्वितीय घटना आईडी (डीडुप्लिकेशन के लिए उपयोग)।

'एक्स-वेबहुक-सेक: 128374' - मोनोटोन अनुक्रम (सदस्यता/विषय द्वारा)।

'एक्स-सिग्नेचर: sha256 = ' - HMAC- подпись।

'एक्स-रेट्री: 0,1,2... 'कोशिश संख्या है।

'एक्स-वेबहुक-संस्करण: 1' - अनुबंध संस्करण।

(वैकल्पिक) 'Traceparent' - सहसंबंध का पता लगाएं।

प्राप्तकर्ता से प्रतिक्रिया

2xx - सफलतापूर्वक स्वीकार किया गया (इस 'आईडी' के लिए कोई और दोहराव नहीं होगा)।

410 गया - समापन बिंदु हटाया/निष्क्रिय - प्रेषक पुनर्प्रेषण को समाप्त करता है और सदस्यता को निष्क्रिय करता है।

429/5xx/timeout - प्रेषक पुनरावृत्ति नीति के अनुसार दोहराता है।

3) पुनर्विचार नीति

अनुशंसित बैकऑफ सीढ़ी (+ jitter)

'1s, 3s, 10s, 30s, 2m, 10m, 30m, 2h, 6h, 24h' (सीमा के बाद रुकें, उदाहरण के लिए 48-72 घंटे)।

नियम:

"झुंड प्रभाव" से बचने के लिए घातीय बैकऑफ + यादृच्छिक जिटर ( 20-30%)।
अस्थायी विफलताओं के लिए त्रुटियों का कोरम (उदाहरण के लिए, पुनः प्रयास करें यदि 5xx या नेटवर्क टाइमआउट)।
429 का सम्मान करें: न्यूनतम 'मिनट' सेट करें (रेट्री-आफ्टर हेडर, अगला बैकऑफ विंडो) '।

टाइमआउट और आकार

कनेक्शन टाइमआउट ≤ 3-5 सेकंड; कुल प्रतिक्रिया समय ≤ 10 सेकंड

अनुबंध के तहत शरीर का आकार (उदाहरण के लिए, 256 KB), अन्यथा 413 - तर्क "चंकिंग" या "पुल URL"।

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

अज्ञात अनुप्रयोग: उसी 'आईडी' के प्रसंस्करण दोहराव को उसी परिणाम को वापस करना चाहिए और फिर से स्थिति को नहीं बदलना चाहिए।

प्राप्तकर्ता की तरफ से डेडअप स्टोरेज: TTL 'रिट्रे विंडो (24-72 घंटे) के साथ स्टोर' (X-Webhook-Id, , checksum) '।

संरचनात्मक कुंजी: यदि कई विषय → '(subscription_id, event_id)'।

5) आदेश और "बिल्कुल एक बार प्रभाव"

वितरित प्रणालियों में सख्त आदेश की गारंटी देना मुश्किल है। उपयोग करें:

कुंजी द्वारा विभाजन: एक ही तार्किक सेट (उदाहरण के लिए, 'ऑर्डर _ आईडी') हमेशा डिलीवरी के एक "चैनल" में होता है।
अनुक्रम: पुराने 'एक्स-वेबहुक-सेक' के साथ घटनाओं को अस्वीकार करें और लापता लोगों के आने से पहले उन्हें "पार्किंग स्थल" में डाल दें।
वास्तव में एक बार प्रभाव प्राप्त किया जाता

लागू ऑपरेशनों का लॉग (आउटबॉक्स/इनबॉक्स पैटर्न),

डेटाबेस में 'इवेंट _ आईडी' द्वारा लेन-देन अपसर्ट,

जटिल प्रक्रियाओं के लिए सागा/मुआवजा।

6) स्थिति कोड द्वारा त्रुटि समाधान (तालिका)

प्रतिक्रिया कोड	प्रेषक के लिए मूल्य	क्रिया
2xx	एसीके प्राप्त हुआ	हम वितरित, रोकने पर विचार करते हैं
4xx (410/429 को छोड़ कर)	लगातार त्रुटि (पेलोड/प्राधिकरण)	DLQ में रखें, एकीकरण को सूचित करें
410	समापन बिंदु मिटाया/पदावनत	रिट्रेज़रोकें, सदस्यता निष्क्रिय करें
408/429	अस्थायी ओवरलोड/टाइमआउट	बैकऑफ/जिटर द्वारा दोहराएं; 'रीट्री-आफ्टर' पर विचार करें
5xx	अस्थायी सर्वर त्रुटि	बैकऑफ/जिटर द्वारा दोहराएँ
3xx	वेबहुक के लिए रीडायरेक्ट का उपयोग न करें	कॉन्फ़िगरेशन त्रुटि मानें

7) चैनल सुरक्षा

प्रत्येक संदेश का HMAC हस्ताक्षर; रिसीवर पर "टाइम विंडो" (मिट्टी और रीप्ले अटैक) के साथ जांचें।

संवेदनशील डोमेन (LCC/भुगतान) के लिए mTLS।

निवर्तमान पतों के आईपी मिश्रधातु, टीएलएस 1। 2 +, एचएसटीएस।

पीआईआई कम से कम: अनावश्यक व्यक्तिगत डेटा न भेजें; लॉग में भेस।

रहस्यों का रोटेशन: दो वैध कुंजी (सक्रिय/अगला) और वर्तमान को इंगित करने के लिए 'एक्स-की-आईडी' हेडर।

8) कतारें, डीएलक्यू और रिप्ले

घटनाओं को प्रेषक की ओर से आउटपुट कतार/लॉग पर लिखा जाना चाहिए (विश्वसनीय रीप्ले के लिए).

यदि अधिकतम रिट्रेज़पार हो जाता है, तो घटना कारण के साथ डीएलक्यू (डेड लेटर क्यू) में जाती है।

रीप्ले एपीआई (प्राप्तकर्ता/ऑपरेटर के लिए): आरपीएस प्रतिबंध और अतिरिक्त हस्ताक्षर/प्राधिकरण के साथ 'आईडी '/समय सीमा/विषय द्वारा पुनः स्थापित करें।

रीप्ले एपीआई उदाहरण (प्रेषक):


POST /v1/webhooks/replay
{ "subscription_id": "sub_123", "from": "2025-11-03T00:00:00Z", "to": "2025-11-03T12:00:00Z" }
→ 202 Accepted

9) अनुबंध और संस्करण

घटना ('स्कीमा _ संस्करण' फ़ील्ड) और परिवहन ('एक्स-वेबहुक-संस्करण') का संस्करण करें।

केवल वैकल्पिक के रूप में फ़ील्ड जोड़ विलोपन पर - मामूली प्रवास और संक्रमण अवधि (दोहरी-लिखना)।

दस्तावेज़ घटना प्रकार, उदाहरण, स्कीमा (JSON Schemas), त्रुटि कोड।

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

प्रेषक कुंजी मेट्रिक्स:

'डेलीवरी _ सक्सेस _ रेट' (2xx/सभी प्रयास), 'फर्स्ट _ परफॉर्मेंस _ सक्सेस _ रेट'
'retries _ total', 'max _ retry _ age _ secont', 'dlq _ count'
'latency _ p50/p95' (occurred_at → ack_received_at)

प्राप्तकर्ता कुंजी मेट्रिक्स:

'ac _ latency' ( 2xx प्राप्त करें), 'processing _ latency' (पूछताछ)
'duplicates _ total', 'अवैध _ signature _ total', 'out _ of _ ord _ total'

एसएलओ उदाहरण:

99. 9% घटनाओं को पहला ACK ≤ 60 सेकंड (28 डी) प्राप्त होता है।

DLQ ≤ 0। कुल का 1%; DLQ रीप्ले ≤ 24 घंटे।

11) टाइमिंग और नेटवर्क ब्रेक

समय क्षेत्र में यूटीसी का उपयोग करें; एनटीपी तुल्यकालित करें।

लैग को पढ़ ने के लिए 'hease _ at' भेजें और 'deverate _ at' को ठीक करें।

लंबे ब्रेक के साथ, नेटवर्क/एंडपॉइंट - कतार में जमा होता है, विकास को सीमित करता है (बैकप्रेशर + कोटा)।

12) अनुशंसित सीमा और स्वच्छता

आरपीएस प्रति सदस्यता (उदा। 50 आरपीएस, फट 100) + संगति (उदा। 10).

अधिकतम। निकाय: 64-256 KB; अधिक के लिए - "अधिसूचना + URL" और हस्ताक्षर डाउनलोड करें।

'सांप' में घटना के नाम। केस 'या' डॉट। प्रकार '(' क्रम। बनाया ')।

रिसीवर के लेखन संचालन की सख्त पहचान।

13) उदाहरण: प्रेषक और रिसीवर

13. 1 प्रेषक (स्यूडोकोड)

python def send_event(event, attempt=0):
body = json. dumps(event)
sig = hmac_sha256_base64(body, secret)
headers = {
"X-Webhook-Id": event["id"],
"X-Webhook-Seq": str(event["sequence"]),
"X-Retry": str(attempt),
"X-Signature": f"sha256={sig}",
"Content-Type": "application/json"
}
res = http. post(endpoint, body, headers, timeout=10)
if 200 <= res. status < 300:
mark_delivered(event["id"])
elif res. status == 410:
deactivate_subscription()
else:
schedule_retry(event, attempt+1) # backoff + jitter, respect 429 Retry-After

13. 2 रिसीवर (स्यूडोकोड)

python
@app. post("/webhooks")
def handle():
body  = request. data headers = request. headers assert verify_hmac(body, headers["X-Signature"], secret)
evt_id = headers["X-Webhook-Id"]
if dedup_store. exists(evt_id):
return, "" 204 enqueue_for_processing (body) # fast path. dedup_store put(evt_id, ttl=723600)
return, "" 202 # or 204

14) परीक्षण और अराजकता प्रथाओं

नकारात्मक मामले: अवैध हस्ताक्षर, 429/5xx, टाइमआउट, 410, बड़े पेलोड।

व्यवहार: आउट-ऑफ-ऑर्डर, डुप्लिकेट, 1-10 मिनट की देरी, 24 घंटे के लिए ब्रेक।

लोड: फट 10 ×; बैकप्रेशर और डीएलक्यू दृढ़ ता के लिए जांचें।

अनुबंध: JSON स्कीमा, अनिवार्य शीर्षक, स्थिर घटना प्रकार।

15) कार्यान्वयन चेकलिस्ट

2xx = ACK, और पूछताछ के बाद त्वरित वापसी
एक्सपोनेंशियल बैकऑफ + जिटर, 'रेट्री-आफ्टर' का सम्मान करें
रिसीवर IDempotency और X-Webhook-Id (TTL ≥ Retray)
HMAC हस्ताक्षर, गुप्त रोटेशन, वैकल्पिक mTLS
DLQ + रिप्ले API, मॉनिटरिंग और अलर्ट
सीमाएं: टाइमआउट, आरपीएस, बॉडी साइज़
आदेश: कुंजी या 'अनुक्रम' + "पार्किंग स्थल" द्वारा विभाजन
प्रलेखन: स्कीमा, उदाहरण, त्रुटि कोड, संस्करण
अराजकता परीक्षण: देरी, डुप्लिकेट, नेटवर्क विफलता, लंबी रीप्ले

16) मिनी-एफएक्यू

क्या मुझे हमेशा 200 का जवाब देने की जरूरत है?

कोई भी 2xx एक सफलता के रूप में गिना जाता है। 202/204 "कतार में स्वीकार" के लिए सामान्य अभ्यास है।

रिप्ले रोका जा सकता है?

हां, 410 प्रतिक्रिया और/या प्रेषक के कंसोल/एपीआई (सदस्यता वापस लेना) के माध्यम से।

बड़े पेलोड के बारे में क्या?

"अधिसूचना + सुरक्षित URL" भेजें, डाउनलोड अनुरोध पर हस्ताक्षर करें और TTL संस्थापित करें।

आदेश कैसे सुनिश्चित करें?

कुंजी + 'अनुक्रम' द्वारा विभाजन; विसंगति के मामले में - "पार्किंग स्थल" और फिर से खेलना।

कुल

विश्वसनीय वेबहूक स्पष्ट ACK (2xx) शब्दार्थ हैं, बैकऑफ + जिटर के साथ उचित दोहराव, सख्त निष्क्रियता और डीडुप्लिकेशन, सक्षम सुरक्षा (HMAC/mTLS), कतारें + DLQ + रिप्रेक्ट, और पारसावचन। अनुबंध को ठीक करें, सीमा और मैट्रिक्स दर्ज करें, नियमित रूप से अराजकता के परिदृश्य चलाएं - और आपके एकीकरण बहुत पहले विफलताओं पर "डालना" बंद कर देंगे।

वेबहूक: रिप्ले और पावती

प्रेषक शीर्षिका

प्राप्तकर्ता से प्रतिक्रिया

टाइमआउट और आकार

कुल

हमसे संपर्क करें

त्वरित संपर्क

वीडियो जल्द ही अपडेट किया जाएगा

हम इस समय परियोजनाओं में बहुत व्यस्त हैं