Webhooks: تکرار و قدردانی

1) مدل تحویل پایه

حداقل یک بار (پیش فرض) - این رویداد ≥1 بار تحویل داده خواهد شد. تضمین های دقیق یک بار توسط idempotency گیرنده به دست می آید.
قدردانی (ACK): فقط هر 2xx (معمولا 200/204) از گیرنده به معنای موفقیت است. هر چیز دیگری به عنوان یک شکست تفسیر می شود و منجر به تکرار می شود.
ACK سریع: پاسخ 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
}

سرآیند فرستنده

'X-Webhook-Id: evt_01HXYZ' - شناسه رویداد منحصر به فرد (استفاده برای deduplication).
'X-Webhook-Seq: 128374' - دنباله یکنواخت (با اشتراک/موضوع).
'X-Signature: sha256 = <base64 (hmac_sha256 (body, secret))>' - HMAC- подпись.
"X-Retry: 0,1,2... شماره امتحان است.
'X-Webhook-Version: 1' - نسخه قرارداد.
(اختیاری) 'Traceparent' - همبستگی ردیابی.

پاسخ از دریافت کننده

2xx - با موفقیت پذیرفته شد (تکرارهای بیشتری برای این شناسه وجود نخواهد داشت).
410 Gone - نقطه پایانی حذف شده/غیرفعال → فرستنده مجددا تلاش می کند و اشتراک را غیرفعال می کند.
429/5xx/timeout - فرستنده با توجه به سیاست retray تکرار می شود.

3) سیاست مجدد

توصیه می شود از نردبان برگشت (+ jitter)

'1s، 3s، 10s، 30s، 2m، 10m، 30m، 2h، 6h، 24h' (توقف پس از حد، به عنوان مثال 48-72 ساعت).

• عقب نشینی نمایشی + جرقه تصادفی (± 20-30٪) برای جلوگیری از «اثر گله».
• حد نصاب خطا برای خرابی موقت (به عنوان مثال، retry اگر 5xx یا اتمام وقت شبکه).
• احترام 429: حداقل «دقیقه (هدر Retry-After، پنجره عقب بعدی)» را تنظیم کنید.

زمان و اندازه

مدت زمان اتصال ≤ 3-5 ثانیه ؛ مدت زمان کل پاسخ ≤ 10 ثانیه

اندازه بدنه تحت قرارداد (به عنوان مثال، ≤ 256 کیلوبایت)، در غیر این صورت 413 → منطق «chunking» یا «pull URL».

4) Idempotency و deduplication

برنامه Idempotent: پردازش تکرارهای همان شناسه باید همان نتیجه را بازگرداند و دوباره وضعیت را تغییر ندهد.
ذخیره سازی Dedup در سمت گیرنده: فروشگاه '(X-Webhook-Id، processed_at، checksum)' با TTL ≥ پنجره های retray (24-72 ساعت).
کلید ترکیبی: اگر چندین موضوع → (subscription_id، event_id).

5) سفارش و «اثرات دقیقا یک بار»

• پارتیشن با کلید: همان مجموعه منطقی (به عنوان مثال، 'order _ id') همیشه در یک «کانال» تحویل است.
• ترتیب: رویدادها را با X-Webhook-Seq قدیمی رد کنید و آنها را در «پارکینگ» قرار دهید قبل از اینکه از دست رفته وارد شوید.

• ورود به سیستم از عملیات کاربردی (خروجی/الگوی صندوق),
• افزایش معاملات توسط «event _ id» در پایگاه داده،
• sagas/جبران برای فرآیندهای پیچیده.

6) حل خطا توسط کدهای وضعیت (جدول)

7) امنیت کانال

امضای HMAC هر پیام ؛ گیرنده را با «پنجره زمان» (حملات mitm و replay) بررسی کنید.
mTLS برای دامنه های حساس (LCC/پرداخت).
Allowlist IP از آدرس های خروجی، TLS 1. 2 +، HSTS.

به حداقل رساندن PII: اطلاعات شخصی غیر ضروری را ارسال نکنید ؛ پنهان شدن در لاگ ها

چرخش اسرار: دو کلید معتبر (فعال/بعدی) و هدر 'X-Key-Id' برای نشان دادن فعلی.

8) صف، DLQ و تکرار

رویدادها باید در صف خروجی/ورود به سیستم در طرف فرستنده (برای پخش قابل اعتماد) نوشته شوند.
اگر حداکثر بازپخش بیش از حد باشد، رویداد به DLQ (صف نامه مرده) با علت می رود.
تکرار API (برای گیرنده/اپراتور): ارسال مجدد توسط «id »/محدوده زمانی/موضوع، با محدودیت RPS و امضای اضافی/مجوز.

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

9) قرارداد و نسخه

نسخه رویداد (فیلد «schema _ version») و حمل و نقل («X-Webhook-Version»).
فیلدها را فقط به صورت اختیاری اضافه کنید در حذف - مهاجرت جزئی و دوره انتقال (دو نوشتن).
انواع رویدادهای سند، نمونه ها، طرح ها (طرح های JSON)، کدهای خطا.

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

• 'delivery _ success _ rate' (2xx/همه تلاش ها)، 'first _ attempt _ success _ rate'
• 'retries _ total', 'max _ retry _ age _ seconds', 'dlq _ count'
• 'latency _ p50/p95' (occurred_at → ack_received_at)

• 'ack _ latency' (receive → 2xx), 'processing _ latency' (enqueue → done)
• 'duplicates _ total', 'invalid _ signature _ total', 'out _ of _ order _ total'

99. 9٪ از رویدادها اولین ACK را ≤ 60 ثانیه (28d) دریافت می کنند.

• DLQ ≤ 0 1 درصد از کل ؛ پخش DLQ ≤ 24 ساعت

11) زمان بندی و شکستن شبکه

استفاده از UTC در زمینه های زمان ؛ همگام سازی NTP

ارسال 'رخ داده است در' و ثابت 'تحویل _ در' به خواندن تاخیر.
با وقفه های طولانی، شبکه/نقطه پایانی → در صف جمع می شود، رشد را محدود می کند (فشار پشتی + سهمیه).

12) محدودیت های توصیه شده و بهداشت

RPS در هر اشتراک (به عنوان مثال،. 50 RPS، پشت سر هم 100) + همزمان (به عنوان مثال 10).
حداکثر. بدن: 64-256 کیلوبایت ؛ برای بیشتر - «اطلاع رسانی + URL» و امضای دانلود.

نام رویداد در 'مار. مورد یا نقطه. تایپ کنید «(» سفارش. ایجاد شده است.)

idempointency دقیق از عملیات نوشتن گیرنده.

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، timeout، 410، بارهای بزرگ.
رفتاری: خارج از ترتیب، تکراری، تاخیر 1-10 دقیقه، شکستن برای 24 ساعت.
بار: پشت سر هم 10 × ؛ فشار پشتی و پایداری DLQ را بررسی کنید.
قراردادها: طرح JSON، سرفصل های اجباری، انواع رویداد پایدار.

15) چک لیست پیاده سازی

• 2xx = ACK، و بازگشت سریع پس از درخواست
• عقب نشینی نمایشی + jitter، احترام 'Retry-After'
• گیرنده IDempotency و X-وبهوک-ID (TTL ≥ Retray)
• امضای HMAC، چرخش مخفی، mTLS اختیاری
• DLQ + پخش API، نظارت و هشدارها
• محدودیت ها: مدت زمان، RPS، اندازه بدن
• سفارش: پارتیشن با کلید یا «دنباله» + «پارکینگ»
• مستندات: طرح ها، نمونه ها، کدهای خطا، نسخه ها
• آزمون هرج و مرج: تاخیر، تکراری، شکست شبکه، پخش طولانی

16) مینی سوالات متداول

آیا همیشه باید به 200 سوال پاسخ دهم ؟

هر 2xx به عنوان یک موفقیت محسوب می شود. 202/204 یک روش معمول برای «پذیرش در صف» است.

آیا می توان تکرارها را متوقف کرد ؟

بله، پاسخ 410 و/یا از طریق کنسول/API فرستنده (لغو اشتراک).

در مورد بارهای بزرگ چطور ؟

یک «notification + secure URL» ارسال کنید، درخواست دانلود را امضا کنید و TTL را نصب کنید.

چگونه برای اطمینان از سفارش ؟

پارتیشن با کلید + 'دنباله' ؛ در صورت اختلاف - «پارکینگ» و پخش.

مجموع

وب سایت های قابل اعتماد عبارتند از معانی روشن ACK (2xx)، تکرار منطقی با عقب نشینی + jitter، idempotence دقیق و deduplication، امنیت صالح (HMAC/mTLS)، صف + DLQ + تکرار، و قابلیت مشاهده شفاف. قرارداد را اصلاح کنید، محدودیت ها و معیارها را وارد کنید، به طور مرتب سناریوهای هرج و مرج را اجرا کنید - و یکپارچگی شما در اولین شکست متوقف خواهد شد.