ערבויות משלוח Webhook

HTTP (ראשי תיבות של Webhooks) הם הודעות של מערכת אל מנוי מעל HTTP. הרשת אינה אמינה: תגובות אבודות, מנות מגיעות בשכפולים או מקולקלות. לכן, ערבויות משלוח אינן בנויות ”מעל TCP”, אלא ברמה של פרוטוקול webhook ו-domain idempotency.

מטרת המפתח: לספק לפחות פעם אחת משלוח עם הזמנה לפי מפתח (היכן שצריך), לתת את חומרי המנוי לעיבוד אידמפוטנטי וכלי ליישוב מחדש.

1) רמות אחריות

המאמץ הטוב ביותר - ניסיון חד פעמי, ללא רטראס. מקובל רק לאירועים ”לא חשובים”.
ניתן לשכפל לפחות פעם אחת (מומלץ) - שכפולים שלא בהזמנה, אך האירוע יימסר בתנאי שהמנוי יהיה זמין בתוך זמן סביר.
ביעילות-בדיוק-פעם (ברמת האפקט) - הושג על ידי שילוב של אידמפוטנטיות ואחסון dedup בצד המנוי/שולח. ”בדיוק פעם אחת” תחבורה HTTP אינו אפשרי.

2) חוזה Webhook: מינימום נדרש

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) סדר וסיבתיות

סדר מפתח: הבטחה ”לא תשאיר” רק בתוך ”מחיצה _ key” (למשל. 'player _ id', 'ארנק _ id',' psp _ tx _ id'.
הסדר הגלובלי לא מובטח.
בצד השולח יש תור עם סריאליזציה על ידי מפתח (צרכן אחד/שריד), בצד המקבל יש תיבת דואר אלקטרוני עם '(מקור, event_id)' ובאופן אופטי מחכה ל 'seq' חסר.

אם הפערים קריטיים - לספק למשוך-API 'GET/אירועים? אחרי נקודת ביקורת ל ”להתעדכן ולהתייעץ”.

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

כל רשת נושאת "X-Webhook-Id' יציב.
תיבת הדואר הנכנס של הנמען (event_id): PK - 'מקור + event_id'; חוזר על עצמו ללא ניתוח.
תופעות לוואי (כתיבה לבסיס הנתונים/ארנק) מבוצעות רק פעם אחת כאשר האירוע ”נראה” לראשונה.
עבור פקודות בעלות השפעה, השתמש ב Idempotency-Key ומטמון התוצאה למשך חלון המגש.

5) רטריי, גיבוי וחלונות

• Train to '5xx/timeout/connection error/409-Conflict (מחדש )/429 ".
• אין לחזור על '4xx' מלבד '409/423/429' (ורק עם סמנטיקה עקבית).
• גיבוי מעריכי + מתח מלא: 0. חמש, אחת, שתיים, ארבע, שמונה, עד 'מקסימום = 10-15 דקות'; חלונות מגש מחדש של TTL: למשל, 72 שעות.
• כבוד 'Retry-After' מהמקבל.
• יש תאריך יעד משותף: ”להכיר באירוע כפי שלא נמסר” ולהעביר אותו DLQ.

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

6) DLQ Rive

DLQ - ”בית קברות” של אירועים ארסיים או TTL-פג תוקף עם מידע מטא מלא (מטען, כותרות, שגיאות, ניסיונות, חשיש).
קונסולת אינטרנט/API לנסיעה מחדש (point re-liver) עם עריכה אופציונלית/סודית.
דרגה מוגבלת כונן מחדש ו אצווה-red עדיפות.

7) בטיחות

MTLS (במידת האפשר) או TLS 1. 2+.

1. תוציא לא '(חותמת זמן) מהכותרת, בדוק את חלון ההזזה (לדוגמה, תוך 5 דקות).

8) מכסות, מגבלות שיעור והון עצמי

פייר תור לדייר/מנוי: כך שמנוי/דייר אחד לא יבקיע את הבריכה הכללית.
מכסות ופרץ גבולות לתנועה יוצאת ולכל קצה.
תגובה ל '429': כבוד 'Retry-After', זרם טרול; להגבלה ארוכת טווח - השפלה (שליחת סוגי אירועים קריטיים בלבד).

9) אופן חיים של מנוי

רשום/וידוא: POST endpoint = אתגר/תגובה או אישור out-of-band.
חכירה (אופציונלית): החתימה תקפה עד 'תקף _ to'; הארכה - מפורשת.
סיבוב סודי: "עכשווי _ סודי", "הבא _ סודי" מתג _ at ".
מבחן פינג: אירוע מלאכותי כדי לבדוק את המסלול לפני הפעלת הנושאים העיקריים.
דגימות בריאות: HEAD/GET תקופתי עם בדיקת פרופיל TLS.

10) אבולוציה של מזימות (גרסאות אירוע)

סוג אירוע ורסיונינג: 'תשלום. מורשה. v1 '= ”v2”.
Evolution - Edvolutive (שדות חדשים = גרסאות מינור API), שבירת מספר a חדש.
Schema Register (JSON-Schema/Avro/Protobuf) + אימות אוטומטי לפני ההגשה.
ה-X-Event-Type hader וה-schema _ version 'field בגוף שניהם נדרשים.

11) יכולת תצפית ו ־ SLO

• 'Deliviries _ total', '2xx/4xx/5xx _ rate', 'timeout _ rate', 'חתימה _ fall _ rate'.
• 'attemps _ avg', 'p50/p95/p99 _ latency _ ms' (לפרסם 2xx).
• 'dedup _ rate', 'out _ of _ order _ rate', 'dick _ rate', 'redrive _ success _ rate'.
• 'quue _ extreme', 'vester _ in _ ms', 'strontle _ events'.

• מנת המשלוחים של 60 אס (p95) - 99. 5% לאירועים קריטיים.
• DLQ על 0. 1% ב-24 שעות
• כשל חתימה כולל 0. 05%.

event _ id', 'מחיצה _ key', 'seq', 'track', 'endpoint',' terant _ id', 'schema _ version', 'trace _ id'.

12) אלגוריתם התייחסות לשולח

1. תכתוב אירוע לתיבת ההפעלה.
2. הגדר partition_key וסק; תור.
3. העובד לוקח לפי מפתח, יוצר בקשה, סימנים, שולח עם פסקי זמן (חיבור/קריאה).
4. עם ”2xx” - לזהות כפי שנמסר, לתקן latency ו seq-ביקורת.
5. עם 429/5xx/timeout - נסיגה לפי מדיניות.
6. על ידי TTL # DLQ והתראה.

13) מעבד התייחסות (מקלט)

1. קבל את הבקשה, בדוק TLS/proto.
2. אימות של חתימה וחלון זמן.
3. Fast ACK 2xx (לאחר כתיבה סינכרונית לתור תיבה/תור מקומי).
4. פועל אסינכרוני קורא "תיבת דוא" ל ", בודק" אירוע _ id' (סבא), במידת הצורך, פקודות על ידי "seq 'inside" מחיצה _ key ".
5. מבצע אפקטים, כותב ”נקודת ביקורת קיזוז/סק” לצורך השלמה.
6. במקרה של שגיאה - מגשים מקומיים; משימות ”ארסיות” = DLQ מקומי עם התראות.

14) להשלים (לולאת בריכה)

• 'קבל/אירועים? partition_key=...&after_seq=...&limit=...' - לתת את כל ההחמצות.
• נקודת ביקורת טוקנית: ”after = opaque _ token” במקום seq.
• Idempotent redalivery: אותו "אירוע _ id', אותה חתימה על" t "החדש.

15) כותרות וקודים שימושיים

2xx - מקובל (גם אם עיבוד עסקי הוא מאוחר יותר).
410 Gone - endpoint סגור (השולח מפסיק משלוח ומסמן את המנוי כ ”ארכיון”).
409/423 - חסימה זמנית של המשאב.
429 - לעתים קרובות מדי.
400/401/403/404 - שגיאת הגדרות; עצור את הרטריי, פתח את הכרטיס.

16) רב ־ דיירים ואזורים

תורים בודדים ומגבלות לדייר/נקודת סיום.
תושבות נתונים: שליחת נתונים מהאזור; כותרות מקצה לקצה "X-Tenant'," X-Region ".
בידוד הכישלונות: נפילתו של מנוי אחד אינה משפיעה על השאר (בריכות נפרדות).

17) בדיקה

מבחני חוזה: דוגמאות קבועות של גופים/חתימות, בדיקת אימות.
כאוס: טיפה/כפילויות, סדר ערבוב, עיכובי רשת, 'RST', 'טעויות TLS'.
עומס: פרץ סערה, נמדד p95/p99.
אבטחה: אנטי-שידור חוזר, חותמת זמן מיושנת, סודות שגויים, סיבוב.
DR/Replay: Mass Redrive מ-DLQ בדוכן מבודד.

18) ספרי משחק (ספרי הפעלה)

1. Grown' signal _ fall _ ratte&fost

בדוק סחף שעון, פג תוקף ”סובלנות”, סיבוב של סודות; לאפשר באופן זמני ”סוד כפול”.

2. התור הוא הזדקנות ('vest _ in _ ms' rocking)

הגדלת העובדים, מתן עדיפות לנושאים קריטיים, הפחתת תדירות הטיפוסים ה ”רועשים” באופן זמני.

3. סערה 429 במנוי

אפשר חניקה והפסקות בין ניסיונות; משמרת פחות סוגי אירועים קריטיים.

4. מסה '5xx&fost

מפסק מעגל פתוח עבור נקודת קצה מסוימת, לעבור לדחות & אצווה; אות למנוי.

5. DLQ מאוכלס

עצור הוצאה לאור לא ביקורתית, אפשר הסעה מחדש עם RPS נמוך, להעלות התראות לבעלי מנויים.

19) שגיאות אופייניות

עיבוד כבד סינכרוני לתגובה 2xx * מגשים מחדש ושכפולים.
אין חתימת גוף/זמן החלפה/הפעלה חוזרת.
היעדר "event _ id' ו-" inbox "= לא ניתן ליצור אידמפוטנט.
ניסיון ל ”סדר גלובלי” = תור נצחי ננעל.
נסיגה ללא לחץ/מגבלות = התעצמות תקרית (עדר רועם).
מאגר משותף אחד לכל המנויים. ”רועש” מכניס את כולם.

20) רשימת בדיקות לפני המכירה

[ ] חוזה: "event _ id'," partion _ key "," seq ", event _ type. נ ', חתימת HMAC וחותמת זמן.

[ ] Sender: Out Box, Serialization by Key, מגשים מחדש עם backoff + jitter, TTL, DLQ ו-RED.

[ ] מקבל: כתיבה מהירה לתיבת הדואר הנכנס + 2xx; טיפול אידמפוטנטי; DLQ מקומי.

[ ] אבטחה: TLS, חתימות, אנטי-שידור חוזר, דו-סודי, סיבוב.

[ ] מכסות/גבולות: תור הוגן לדייר/סוף נקודה, כבוד ”Retry-After”.

[ ] ליישב אפיקים ומחסומים; תיעוד למנויים.

[ ] תצפית: p95/threads/errors/DLQ, עקבות ל- "event _ id'.

[ ] מאורע וסכמות מדיניות האבולוציה.

[ ] חוברות משחקים וכפתור הפוגה/הפשרה גלובליים.

מסקנה

קובצי אינטרנט מהימנים הם פרוטוקול על גבי HTTP, לא רק "POST עם JSON. "חוזה ברור (ID, סדר מפתח, חתימה), אידמפוטנטיות, מגש עם ג 'יטר, תור הוגן וחוברות השמעה היטב הופכים את המקרה הטוב ביותר למנגנון מסירה צפוי ומדיד. לבנות לפחות פעם אחת + סדר מפתח + ליישב, והמערכת תשרוד בשלווה את הרשת, לטעון פסגות ושגיאות אנושיות.