חוברות אינטרנט ואימפוטנציה של אירוע

TL; DR

Webhook הוא דגם חתום (HMAC/MTLS), מסכם ואירוע אידמפוטנטי המועבר במודל של לפחות פעם אחת עם גיבוי מעריכי ושכפול אצל הנמען. מסכים על מעטפה (”event _ id',” tis ”,” ts', ”ts”, ”treasure”, ”time”), חלון זמן (lime 5 דקות), קודי תגובה, מגשים מחדש, DLQ ו-status endpoint.

1) תפקידים ומודל משלוח

Sender (אתה/ספק): יוצר אירוע, סימנים, מנסה לספק עד 2xx, רטריט ב-3xx/4xx/5xx (פרט ל ”לא מקבל” מפורש), מוביל DLQ, נותן שידור חוזר API.
הנמען (השותף/השירות שלך): בודק את חלון החתימה/זמן, יוצר dedup ועיבוד אידמפוטנטי, מגיב עם הקוד הנכון, מספק/סטטוס ו/ack שידור חוזר על ידי "event _ id'.

אחריות: לפחות פעם אחת. הנמען חייב להיות מסוגל להתמודד עם שכפולים והזמנה מחדש.

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"
}
}

שדות נדרשים הם ”event _ id',” type ”,” version ”,” ts', ”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') -30S
• 'X-Event-Id' t מעובד לפני (dedup)
• X-חתימה 'מאצ' ים (השוואה בזמן בטוח)

3. 2 אמצעי add. mode

MTLS לספרי אינטרנט רגישים ביותר.
רשימת הרשאות IP/ASN.
DPoP (אופציונלי) עבור שולח מוגבל אם Overhook יוזם התקשרות.

4) אידמפוטנטיות ושכפול

4. אידמפוטנטיות של אירוע 1

• Stors 'Event _ id' in the idempotent cache (KV/Redis/DB) ב-TTL, 24-72 שעות;
• חוסך את תוצאת העיבוד (הצלחה/שגיאה, חפצים) לחזרה מחדש.

4. 2 idempotency פקודה (callbacks)

אם ה-Webhook מאלץ את הלקוח למשוך את API (לדוגמה, ”לאשר את התשלום”), השתמש ב-Idempotency-Key בקריאת ה-REST, לאחסן את התוצאה בצד השירות (בדיוק-פעם אחת).

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

5) רטריי והתרחק

• חמישים, חמש עשרה, שלושים, עשר, עשרים מטר, חמישים, עשר מטר, שלושים, אחת, שלוש, שש, שש, שתיים עשרה, עשרים וארבע

• הצלחה של 2xx, להפסיק מגשים מחדש.

• '400/ 401/403/404/422' - לא ניתן מחדש אם החתימה/פורמט הוא בסדר (טעות הלקוח).
• '429 - מחדש על ידי' Retry-After 'or לסגת.
• 5xx/רשת - רטריום.

כותרות שולח: ”User-Agent”, ”X-Webhook-Productor”, ”X-Trance”.

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

Transactionality: התווית ”נראית” חייבת להיות מוגדרת באופן אטומי עם השפעת הפעולה (או לאחר תיקון התוצאה) כדי למנוע עיבוד כפול של כשל.

7) ערבויות של סדר ותמונות

הסדר לא מובטח. השתמש ב- "ts' ו- domain 'seq '/' in' data 'כדי לאמת רלוונטיות.
עבור lags/assess - הוסף/שידור חוזר בשולח ו/רסינק במקלט (קבל תצלום ודלתות בחלון הזמן/זיהוי).

8) מצב, שידור חוזר ו ־ DLQ

8. 1 נקודות סוף השולח

'POST/Webhooks/Retway' על ידי 'אירוע _ id' רשימה או על ידי חלון הזמן.
'Get/webooks/events/: id - להראות את חבילת המקור ואת ההיסטוריה של ניסיונות.
DLQ: אירועים ”מתים” (מגבלת המגש הותשה) = אחסון נפרד, התראות.

8. 2 נקודות קצה למקבל

'GET/ webhooks/status/:event_id'' - ראה = אמת/שקר ',' מעובד _ at ',' מטפל _ גרסה '.
(אופציונלי) אישור של עיבוד ידני מ 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..."
}

המלצות: תמיד להחזיר קוד ברור, במידת האפשר, ”Retry-After”. אל תחזיר פרטי אבטחה מפורטים.

10) ניטור ו ־ SLO

• משלוח p50/p95, אחוזי הצלחה, מגש/אירוע, DLQ טיפה, לחלוק 2xx/4xx/5xx, חלון עיכוב עד 2xx.

• ודא שיעור כשל (חתימה/זמן), דופ-קצב, מטפל latency p95, 5xx.

• משלוח: 99. 9% מהאירועים מקבלים 2xx <3 c p95 (לאחר הניסיון המוצלח הראשון).
• אימות קריפטוגרפי: אימות חתימה על 2-5 ms p95.
• דדאפ: 0 אפקטים חוזרים (תוצאה של פעם אחת בדיוק ברמת התחום).

11) ביטחון נתונים ופרטיות

אל תשדר PAN/PII בגוף של webhook; השתמש בתעודות זהות ולאחר מכן למשוך לפרטים נגד API מורשה.
שדות רגישים מסכה ביומנים; חנויות גופות אירועים רק עד למינימום, עם טי-טי-אל.
הצפן חנויות DLQ והילוך חוזר.

12) ורסינציה ותאימות

גרסה ב ”גירסה” (מעטפה) ובמעבר: '/webhooks/v1/תשלומים '.
שדות חדשים הם אופציונליים; הסרה - רק לאחר תקופת השקיעה.
תיעד את השינויים בצ 'נגלוג הניתן לקריאה במכונה (לבדיקות אוטומטיות).

13) מקרי מבחן (רשימת בדיקות UAT)

[ ] מחדש את אותו "אירוע _ id' אפקט אחד ו '200' לשכפולים.

[ חתימה ]: מפתח נכון, מפתח שגוי, מפתח ישן (סיבוב), ”X-Timestamp” מחוץ לחלון.

[ ] Backoff: הנמען נותן '429 &fost with' Retry-After '# הפסקה נכונה.

[ סדר ]: אירועים "... מעובד 'לבוא לפני'... נוצר "תקין עיבוד/המתנה.

[ ] כשל מסד הנתונים במקלט בין ”סימן _ ראה” לאטומיציה/חזרה.

[ ] DLQ והילוך חוזר ידני = מסירה מוצלחת.

[ ] המוני ”סערה” (הספק שולח חבילות).

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) שגיאות תכופות

אין dauplication = אפקטים חוזרים (double reflands/payouts).
חתימה ללא חותמת זמן/חלון = פגיע הילוך חוזר.
אחסון סוד אחד HMAC על כל השותפים.
תגובות 200.200&ft לפני תיקון התוצאה = אובדן אירועי התרסקות.
”לשטוף” פרטי אבטחה לתשובות/יומנים.
היעדר DLQ/שידור חוזר - תקריות הן בלתי פתירות.

גיליון רמאות מימוש 16

אבטחה: HMAC v1 + "X-Timestamp" + "X-Event-Id', חלון 5 דקות; הרשאות MTLS/IP כנדרש.
נושא: ”event _ id',” type ”,” ts', ”ts”, ”tense”, ”data”.
משלוח: לפחות פעם אחת, חזרה עם ג 'יטר,' Retry-After ', DLQ + הילוך חוזר API.
Idempotency: KV-cache 24-72 h, קיבעון אטומי של האפקט + ”mark _ seat”.
תצפית: משלוח, חתימה, שכפול מדדים; trace _ id.
תיעוד: גרסה, קודי תגובה, דוגמאות, רשימת בדיקות UAT.

המשך תקציר

קורות רשת עקשניות בנויות על שלושה לווייתנים: מעטפה חתומה, לפחות פעם אחת משלוח ועיבוד אידמפוטנטי. לארגן את החוזה, לאפשר HMAC/mTLS ואת חלון הזמן, ליישם את retrai + DLQ ולהפעיל מחדש, לאחסן תוויות אידמפוטנטיות וללכוד אפקטים אטומיים. אז האירועים נשארים אמינים גם עם כשלים ברשת, לטעון פסגות ו ”כפילויות של גורל” נדירות.