वेबहूक और इवेंट आइडेम्पोटेंसी

टीएल; डीआर

एक अच्छा वेबहुक एक हस्ताक्षरित (HMAC/mTLS) है, जो प्राप्तकर्ता पर घातीय बैकऑफ और डीडुप्लिकेशन के साथ कम से कम एक बार मॉडल पर दिया जाता है। एक लिफाफे पर सहमत हों ('ईवेंट _ आईडी', 'टाइप', 'टीएस', 'संस्करण', 'प्रयास', 'हस्ताक्षर'), समय विंडो (≤5 मिनट), प्रतिक्रिया कोड, पुनरावृत्ति, डीएलक्यू और स्थिति समापन बिंदु।

1) भूमिका और वितरण मॉडल

प्रेषक (आप/प्रदाता): एक घटना उत्पन्न करता है, संकेत देता है, 2xx तक वितरित करने की कोशिश करता है, 3xx/4xx/5xx (स्पष्ट "स्वीकार न करें" को छोड़ कर), डीएलक्यू का नेतृत्व करता है, रीप्य एपीआई देता है।

प्राप्तकर्ता (पार्टनर/आपकी सेवा): हस्ताक्षर/समय विंडो की जाँच करता है, डीडअप और पहचान प्रसंस्करण बनाता है, सही कोड के साथ जवाब देता है, 'घटना _ आईडी' द्वारा/स्थिति और/ack रीप्ले प्रदान करता है।

वारंटी: कम से कम एक बार। प्राप्तकर्ता को डुप्लिकेट और पुनर्आदेश को संभालने में सक्षम होना चाहिए।

2) घटना का लिफाफा

json
{
"event_id": "01HF7H9J9Q3E7DYT5Y6K3ZFD6M",
"type": "payout.processed",
"version": "2025-01-01",
"ts": "2025-11-03T12:34:56.789Z",
"attempt": 1,
"producer": "payments",
"tenant": "acme",
"data": {
"payout_id": "p_123",
"status": "processed",
"amount_minor": 10000,
"currency": "EUR"
}
}

आवश्यक क्षेत्र हैं 'घटना _ id', 'प्रकार', 'संस्करण', 'ts', 'प्रयास'.

एवोल्यूशन नियम: क्षेत्र जोड़ें हटाएँ/बदलें प्रकार - केवल नए 'संस्करण' के साथ।

3) सुरक्षा: हस्ताक्षर और बाध्यकारी

3. 1 HMAC हस्ताक्षर (डिफ़ॉल्ट अनुशंसित)

X-Signature: v1=base64(hmac_sha256(<secret>, <canonical>))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF7...

<timestamp>\n<method>\n<path>\n<sha256(body)>

• Abs (अब − 'X-Timestamp') ≤ 300s
• 'X-Event-Id' not से पहले संसाधित (dedup)
• 'एक्स-सिग्नेचर' मैच (समय-सुरक्षित तुलना)

3. 2 Add। उपाय

अत्यधिक संवेदनशील वेबहुक के लिए mTLS।

IP/ASN अनुमति-सूची।

यदि वेबहुक कॉलबैक शुरू करता है तो प्रेषक-विवश के लिए DPoP (वैकल्पिक)।

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

4. 1 घटना पहचान

• TTL ≥ 24-72 घंटे पर 'इवेंट _ id' in idempotent कैश (KV/Redis/DB) स्टोर करता है;
• री-रिटर्न के लिए प्रसंस्करण परिणाम (सफलता/त्रुटि, कलाकृतियां) बचाता है।

4. 2 कमांड पहचान (कॉलबैक)

यदि वेबहुक ग्राहक को एपीआई (उदाहरण के लिए, "भुगतान की पुष्टि") खींचने के लिए मजबूर करता है, तो आरईएस कॉल पर 'आइडेम्पोटेंसी-की' का उपयोग करें, परिणाम को सेवा पक्ष (बिल्कुल एक बार परिणाम) पर संग्रखें।

key: idempotency:event:01HF7...
val: { status: "ok", processed_at: "...", handler_version: "..." }
TTL: 3d

5) रेट्राई और बैकऑफ

• '5s, 15s, 30, 1m, 2m, 5m, 10m, 30m, 1h, 3h, 6h, 12h, 24h' (फिर रोजाना एन दिनों तक)

• 2xx - सफलता, पीछे हटना बंद करो।

• '400/ 401/403/404/422' - यदि हस्ताक्षर/प्रारूप ठीक है (क्लाइंट त्रुटि) नहीं है।
• '429' - 'रेट्री-आफ्टर' या बैकऑफ द्वारा रिट्रीम।
• 5xx/नेटवर्क - रिट्रीम।

प्रेषक हेडर: 'उपयोगकर्ता-एजेंट', 'एक्स-वेबहुक-निर्माता', 'एक्स-प्रयास'।

6) रिसीवर साइड प्रोसेसिंग

pseudo verify_signature()
if abs(now - X-Timestamp) > 300s: return 401

if seen(event_id):
return 200 // идемпотентный ответ

begin transaction if seen(event_id): commit; return 200 handle(data)       // доменная логика mark_seen(event_id)    // запись в KV/DB commit return 200

ट्रांसक्रियाशीलता: विफलता पर दोहरे प्रसंस्करण से बचने के लिए ऑपरेशन के प्रभाव (या परिणाम को ठीक करने के बाद) के साथ "देखा" लेबल को परमाणु रूप से सेट किया जाना चाहिए।

7) ऑर्डर और स्नैपशॉट की गारंटी

आदेश की गारंटी नहीं है। प्रासंगिकता सत्यापित करने के लिए 'ts' और डोमेन 'seq '/' संस्करण' का उपयोग करें।

लंबे लैग्स/हानियों के लिए - रिसीवर पर प्रेषक और/resync पर जोड़ें/फिर से खेलें (समय/आईडी विंडो पर स्नैपशॉट और डेल्टा प्राप्त करें)।

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

8. 1 प्रेषक समापन बिंदु

'POST/webhooks/repray' - 'event _ id' list या टाइम विंडो द्वारा।

'GET/webhooks/events/: id' - स्रोत पैकेज और प्रयासों का इतिहास दिखाएं।

DLQ: "मृत" घटनाएँ (रिट्रे सीमा समाप्त हो गई है) → अलग भंडारण, अलर्ट।

8. 2 प्राप्तकर्ता समापन बिंदु

'GET/ webhooks/status/: event_id' -' देखा = true/fall ',' processed _ at ',' हैंडलर _ version '।

'POST/webhooks/ack' - (वैकल्पिक) DLQ से मैनुअल प्रसंस्करण की पुष्टि।

9) त्रुटि अनुबंध (रिसीवर प्रतिक्रिया)

http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Retry-After: 120
X-Trace-Id: 4e3f...

{
"error": "invalid_state",
"error_description": "payout not found",
"trace_id": "4e3f..."
}

सिफारिशें: हमेशा एक स्पष्ट कोड वापस करें और, यदि संभव हो तो, 'रेट्री-आफ्टर'। विस्तृत सुरक्षा विवरण वापस न करें।

10) निगरानी और एसएलओ

• डिलीवरी p50/p95, सफलता दर, रिट्रे/इवेंट, ड्रॉप-रेट डीएलक्यू, 2xx/4xx/5xx, 2xx तक की देरी विंडो साझा करें।

• सत्यापित विफल दर (हस्ताक्षर/समय), डुप-दर, विलंबता हैंडलर p95, 5xx।

• डिलीवरी: ≥ 99। 9% घटनाओं को 2xx <3 c p95 (पहले सफल प्रयास के बाद) प्राप्त होता है।
• क्रिप्टोग्राफिक सत्यापन: हस्ताक्षर सत्यापन ≤ 2-5 ms p95।
• डेडअप: 0 बार-बार प्रभाव (डोमेन स्तर पर एक बार परिणाम)।

11) डेटा सुरक्षा और गोपनीयता

वेबहुक के शरीर में पैन/पीआईआई संचारित न करें; आईडी का उपयोग करें और फिर अधिकृत एपीआई के खिलाफ विवरण के लिए खींचें।

लॉग में मास्क संवेदनशील क्षेत्र; टीटीएल के साथ स्टोर इवेंट बॉडी केवल न्यूनतम तक।

DLQ स्टोर और रीप्ले एन्क्रिप्ट करें।

12) वर्शनिंग और संगतता

'संस्करण' (लिफाफा) और पारगमन में संस्करण: '/वेबहुक/v1/भुगतान '।

नए क्षेत्र वैकल्पिक हैं; हटाना - केवल 'सूर्यास्त' अवधि के बाद।

मशीन पढ़ ने योग्य चेंजलॉग में परिवर्तन का दस्तावेज़ (स्वतः जाँच के लिए).

13) परीक्षण मामले (यूएटी चेकलिस्ट)

• डुप्लिकेट करने के लिए एक ही 'इवेंट _ आईडी' - एक प्रभाव और '200' को फिर से वितरित करना।
• हस्ताक्षर: सही कुंजी, गलत कुंजी, पुरानी कुंजी (घूर्णन), 'X-Timestamp' विंडो से बाहर.
• बैकऑफ: प्राप्तकर्ता '429' with 'Retry-After' → सही ठहराव देता है।
• आदेश: घटनाएँ '... संसाधित 'पहले आओ'... बनाया '→ सही प्रसंस्करण/प्रतीक्षा।
• प्रभाव और 'मार्क _ सीज़' → atomicity/दोहराने के बीच रिसीवर पर डेटाबेस विफलता।
• डीएलक्यू और मैनुअल रीप्ले - सफल डिलीवरी।
• मास "स्टॉर्म" (प्रदाता पैक भेजता है) - नुकसान के बिना, सीमाएं महत्वपूर्ण नहीं हैं।

14) मिनी स्निपेट्स

pseudo body = json(event)
canonical = ts + "\n" + "POST" + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
headers = {"X-Timestamp": ts, "X-Event-Id": event.event_id, "X-Signature": "v1="+sig}
POST(url, body, headers)

pseudo assert abs(now - X-Timestamp) <= 300 assert timingSafeEqual(hmac(secret, canonical), sig)

if kv.exists("idemp:"+event_id): return 200

begin tx if kv.exists("idemp:"+event_id): commit; return 200 handle(event.data)        // доменная логика kv.set("idemp:"+event_id, "ok", ttl=259200)
commit return 200

15) बार-बार त्रुटियाँ

कोई deduplication → बार-बार प्रभाव (डबल refands/payouts)।

टाइमस्टैम्प/विंडो के बिना हस्ताक्षर → फिर से भेद्यता।

सभी भागीदारों पर एक HMAC रहस्य का भंडारण।

परिणाम को ठीक करने के लिए प्रतिक्रियाएं '200' before दुर्घटना की हानि।

जवाब/लॉग में "वॉशिंग आउट" सुरक्षा विवरण।

डीएलक्यू/रीप्ले की कमी - घटनाएं अनसुलझी हैं।

16) कार्यान्वयन धोखा शीट

सुरक्षा: HMAC v1 + 'X-Timestamp' + 'X-Event-Id', विंडो ≤ 5 मिनट; mTLS/IP अनुमति-सूची जैसा आवश्यक है.

Конверт: 'इवेंट _ आईडी', 'टाइप', 'संस्करण', 'टीएस', 'प्रयास', 'डेटा'।

डिलीवरी: कम से कम एक बार, जिटर के साथ बैकऑफ, 'रेट्री-आफ्टर', डीएलक्यू + रीप्ले एपीआई।

पहचान: केवी-कैश 24-72 एच, प्रभाव का परमाणु निर्धारण + 'मार्क _ देखा'।

अवलोकन: वितरण, हस्ताक्षर, डुप्लिकेट मैट्रिक्स; ट्रेस _ id।

प्रलेखन: संस्करण, प्रतिक्रिया कोड, उदाहरण, यूएटी चेकलिस्ट।

सारांश फिर से शुरू करें

लगातार वेबहूक तीन व्हेल पर बनाए गए हैं: एक हस्ताक्षरित लिफाफा, कम से कम एक बार डिलीवरी और पहचान प्रसंस्करण। अनुबंध को औपचारिक रूप दें, HMAC/mTLS और टाइम विंडो सक्षम करें, रेट्राई + DLQ और रीप्ले लागू करें, पहचान लेबल स्टोर करें और प्रभाव को परमाणु रूप से कैप्चर करें। फिर घटनाएं नेटवर्क विफलताओं, लोड चोटियों और दुर्लभ "भाग्य के दोहराव" के साथ भी विश्वसनीय रहती हैं।