Webhook گارانتی تحویل

Webhooks اطلاعیه های سیستم به مشترک ناهمزمان بیش از HTTP (S) است. شبکه غیر قابل اعتماد است: پاسخ ها گم می شوند، بسته ها تکراری می شوند یا از نظم خارج می شوند. بنابراین، تضمین تحویل «بیش از TCP» ساخته نشده است، اما در سطح پروتکل webhook و idempotency دامنه.

هدف کلیدی: برای ارائه حداقل یک بار تحویل با سفارش توسط کلید (در صورت لزوم)، به مواد مشترک برای پردازش idempotent و یک ابزار آشتی برای بازیابی.

1) سطح گارانتی

بهترین تلاش - تلاش یک بار، بدون retras. قابل قبول فقط برای رویدادهای «بی اهمیت».
حداقل یک بار (توصیه می شود) - تکراری و خارج از سفارش ممکن است، اما این رویداد تحویل داده خواهد شد در صورتی که مشترک در مدت زمان معقول در دسترس است.
به طور موثر دقیقا یک بار (در سطح اثر) - به دست آمده توسط ترکیبی از idempotency و ذخیره سازی 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) نظم و علیت

ترتیب کلید: تضمین «ترک نخواهد کرد» تنها در داخل یک «partition _ key» (به عنوان مثال 'player _ id', 'wallet _ id', 'psp _ tx _ id').
نظم جهانی تضمین شده نیست.
در سمت فرستنده یک صف با سریال سازی توسط کلید (یک مصرف کننده/sharding) وجود دارد، در سمت گیرنده یک صندوق ورودی با «(منبع، event_id)» و به صورت اختیاری در انتظار «seq» از دست رفته وجود دارد.

اگر شکاف ها حیاتی هستند - ارائه pull-API 'GET/رویدادها ؟ بعد از = ایست بازرسی 'برای «گرفتن و مشورت».

4) Idempotency و deduplication

هر صفحه وب دارای یک «X-Webhook-Id» پایدار است.
گیرنده "صندوق ورودی (event_id)" را ذخیره می کند: PK - "منبع + event_id' ؛ تکرار → بدون عملیات.
عوارض جانبی (نوشتن به پایگاه داده/کیف پول) تنها یک بار انجام می شود زمانی که رویداد برای اولین بار «دیده می شود».
برای دستورات با اثر، استفاده از Idempotency-Key و کش نتیجه برای مدت زمان پنجره retray.

5) Retrai، عقب نشینی و پنجره ها

• Retrain to '5xx/timeout/connection error/409-Conflict (قابل بازیابی )/429'.
• در «4xx» به جز «409/423/429» (و فقط با معانی سازگار) عقب نشینی نکنید.
• عقب نشینی نمایشی + لرزش کامل: 0. 5s، 1s، 2s، 4s، 8s،... تا 'حداکثر = 10-15 دقیقه' ؛ پنجره های TTL retray: به عنوان مثال، 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 и redrive

DLQ - «گورستان» رویدادهای سمی یا TTL-منقضی شده با اطلاعات متا کامل (بارگیری، هدر، خطا، تلاش، هش).
کنسول وب/API برای redrive (تحویل مجدد نقطه) با ویرایش اختیاری نقطه پایانی/مخفی.
نرخ محدود redrive و دسته redrive اولویت بندی.

7) ایمنی

mTLS (در صورت امکان) یا TLS 1. 2+.

1. «t» (برچسب زمان) را از هدر استخراج کنید، پنجره کشویی را بررسی کنید (به عنوان مثال، ± 5 دقیقه).

8) سهمیه ها، محدودیت های نرخ و حقوق صاحبان سهام

صف عادلانه در هر مستاجر/مشترک: به طوری که یک مشترک/مستاجر می کند استخر به طور کلی نمره نیست.
سهمیه ها و محدودیت های انفجاری برای ترافیک خروجی و هر نقطه پایانی.
واکنش به «429»: افتخار «Retry-After»، جریان ترول ؛ برای محدود کردن طولانی مدت - تنزل (ارسال تنها انواع رویداد بحرانی).

9) چرخه عمر اشتراک

ثبت نام/تأیید: POST endpoint → چالش/پاسخ یا تأیید خارج از باند.

اجاره نامه (اختیاری): امضا تا 'valid _ to' معتبر است ؛ طولانی شدن - صریح

چرخش مخفی: «current _ secret»، «next _ secret» с «switch _ at».
تست پینگ: یک رویداد مصنوعی برای تست مسیر قبل از روشن کردن موضوعات اصلی.
نمونه های بهداشتی: HEAD/GET دوره ای با تاخیر و بررسی مشخصات TLS.

10) تکامل طرح ها (نسخه های رویداد)

نوع رویداد نسخهبندی: "پرداخت. مجاز است. v1 → '... v2'.
تکامل - افزودنی (زمینه های جدید → نسخه های MINOR API)، شکستن → نوع جدید.
ثبات طرحواره (JSON-Schema/Avro/Protobuf) + اعتبارسنجی خودکار قبل از ارسال.
هدر «X-Event-Type» و فیلد «schema _ version» در بدن هر دو مورد نیاز است.

11) قابلیت مشاهده و SLO

• 'deliveries _ total', '2xx/4xx/5xx _ rate', 'timeout _ rate', 'signature _ fail _ rate'.
• 'attempts _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (publish to 2xx).
• 'dedup _ rate'، 'out _ of _ order _ rate'، 'dlq _ rate'، 'redrive _ success _ rate'.
• 'queue _ depth', 'oldest _ in _ queue _ ms', 'throttle _ events'.

• سهم تحویل ≤ 60 بازدید کنندگان (P95) - 99. 5٪ برای حوادث بحرانی.
• DLQ ≤ 0 1% در 24 ساعت
• شکست امضا ≤ 0. 05%.

Логи/трейсинг: 'event _ id'، 'partition _ key'، 'seq'، 'تلاش'، 'endpoint'، 'tenant _ id'، 'schema _ version'، 'trace _ id'.

12) الگوریتم مرجع فرستنده

1. رویداد را در صندوق خروجی معاملاتی بنویسید.
2. تعریف partition_key و SEQ ؛ صف.
3. کارگر با کلید می گیرد، درخواست می کند، امضا می کند، با وقفه می فرستد (اتصال/خواندن).
4. با '2xx' - تشخیص به عنوان تحویل، رفع تاخیر و seq-checkpoint.
5. با '429/5xx/timeout' - عقب نشینی با توجه به سیاست.
6. توسط TTL → DLQ و هشدار.

13) پردازنده مرجع (گیرنده)

1. درخواست را قبول کنید، TLS/proto را بررسی کنید.
2. اعتبار سنجی امضا و پنجره زمان.
3. ACK 2xx سریع (پس از نوشتن همزمان به صندوق ورودی/صف محلی).
4. کارگر آسنکرون "inbox" را می خواند، "event _ id" (پدربزرگ) را چک می کند، در صورت لزوم، دستورات "seq 'inside" partition _ key "را بررسی می کند.
5. انجام اثرات، می نویسد: «ایست بازرسی افست/SEQ» برای آشتی.
6. در صورت خطا - retrays محلی ؛ وظایف «سمی» → DLQ محلی با هشدار.

14) آشتی (حلقه استخر)

• 'دریافت/حوادث ؟ partition_key=...&after_seq=...&limit=...' - برای دادن همه از دست رفته.
• Token checkpoint: 'after = opaque _ token' به جای seq.
• تحویل مجدد ایده آل: همان «event _ id»، همان امضا در «t» جدید.

15) عناوین و کدهای مفید

2xx - پذیرفته شده (حتی اگر پردازش کسب و کار بعدا انجام شود).
۴۱۰ Gone - نقطه پایانی بسته است (فرستنده تحویل را متوقف می کند و اشتراک را به عنوان «بایگانی» علامت گذاری می کند).
۴۰۹/۴۲۳ - مسدود کردن موقت منبع → retray منطقی است.
429 - اغلب → دریچه گاز و عقب نشینی.
400/401/403/404 - خطای پیکربندی ؛ قطار را نگه دار، بليط را باز کن.

16) چند مستاجر و مناطق

صف های فردی و محدودیت های هر مستاجر/نقطه پایانی.
اقامت داده ها: ارسال داده ها از منطقه ؛ عنوانهای end-to-end «X-Tenant»، «X-Region».
جداسازی شکست: سقوط یک مشترک بر بقیه (استخرهای جداگانه) تاثیر نمی گذارد.

17) تست کردن

تست های قرارداد: نمونه های ثابت از بدن/امضا، بررسی اعتبار سنجی.
هرج و مرج: رها کردن/تکراری، نظم زدن، تاخیر شبکه، 'RST'، 'TLS' خطا.
بار: پشت سر هم طوفان، اندازه گیری p95/p99.
امنیت: ضد پخش، برچسب زمانی قدیمی، اسرار اشتباه، چرخش.
DR/پخش: جرم redrive از DLQ در موضع جدا شده است.

18) کتاب های بازی (کتاب های اجرا)

1. رشد «امضا _ شکست _ نرخ»

بررسی رانش ساعت، «تحمل» منقضی شده، چرخش اسرار ؛ به طور موقت «راز دوگانه» را فعال کنید.

2. صف قدیمی است ('oldest _ in _ queue _ ms' ↑)

کارگران را افزایش دهید، اولویت بندی موضوعات مهم را فعال کنید، به طور موقت فرکانس انواع «پر سر و صدا» را کاهش دهید.

3. طوفان «429» در مشترک

فعالسازی کاهش و مکث بین تلاشها ؛ انواع وقایع کمتر بحرانی را تغییر دهید.

4. جرم «5x»

مدار شکن باز برای یک نقطه پایانی خاص، سوئیچ به تعویق انداختن & دسته ای ؛ سیگنال به مشترک

5. پر کردن DLQ

توقف انتشار غیر بحرانی، فعال دسته redrive با RPS کم، افزایش هشدار به صاحبان اشتراک.

19) خطاهای معمول

تلاش برای «نظم جهانی» → قفل صف ابدی

پردازش سنگین همزمان به پاسخ 2xx → retrays و تکراری.
بدون امضای پنجره بدن/زمان → جایگزینی/پخش آسیب پذیری.
فقدان «event _ id» و «inbox» → را نمیتوان بیاثر کرد.
Retreats without jitter/limits → تشدید حادثه (رعد و برق گله).
یک استخر مشترک برای همه مشترکین → «پر سر و صدا» قرار می دهد همه.

20) چک لیست پیش فروش

• قرارداد: «event _ id»، «partition _ key»، «seq»، «event _ type». vN '، امضای HMAC و برچسب زمان.
• فرستنده: صندوق پستی، سریال سازی با کلید، retrays با برگشت + jitter، TTL، DLQ و redrive.
• گیرنده: نوشتن سریع به صندوق پستی + 2xx ؛ درمان بی نظیر ؛ DLQ محلی
• امنیت: TLS، امضا، ضد پخش، دو راز، چرخش.
• سهمیه ها/محدودیت ها: صف عادلانه برای هر مستاجر/نقطه پایانی، احترام به «Retry-After».
• آشتی دادن API ها و ایست های بازرسی ؛ مستندات برای مشترکین
• قابلیت مشاهده: p95/threads/errors/DLQ، ردیابی به 'event _ id'.
• نسخه بندی رویداد و سیاست تکامل طرح.
• playbooks حادثه و دکمه مکث/یخ زدگی جهانی.

نتیجه گیری

وب سایت های قابل اعتماد یک پروتکل در بالای HTTP هستند، نه فقط POST با JSON. یک قرارداد روشن (ID، کلید سفارش، امضا)، idempotency، retray با jitter، صف عادلانه و playbooks به خوبی debugged تبدیل بهترین مورد را به یک مکانیزم تحویل قابل پیش بینی و قابل اندازه گیری است. ساخت حداقل یک بار + سفارش کلید + آشتی، و سیستم آرام زنده ماندن شبکه، قله بار و خطاهای انسانی.