Webhook жеткирүү кепилдиктери

Вебхактар - HTTP (S) аркылуу "системадан абонентке" асинхрондук билдирүүлөр. Тармак ишенимдүү эмес: жооптор жоголот, пакеттер дубликаттар менен же тартиптен тышкары келет. Ошондуктан жеткирүү кепилдиктери "TCP боюнча" эмес, веб-хук протоколунун жана домендик идемпотенттүүлүктүн деңгээлинде курулат.

Негизги максаты: ачкычы менен ат-least-once жеткирүү камсыз кылуу (зарыл болгон жерде), калыбына келтирүү үчүн демпотент иштетүү жана reconcile куралы үчүн абонент материалдарды берүү.

1) Кепилдик деңгээли

Best-effort - бир жолку аракет, эч кандай retrains. Бул "маанилүү эмес" окуялар үчүн гана кабыл алынат.
At-least-once (сунушталат) - дубликаттар жана out-of-order болушу мүмкүн, бирок иш-чара акылга сыярлык мөөнөттө абонент болушу шартында жеткирилет.
Effectively-exactly-once (эффект деңгээлинде) - жазылуучу/жөнөтүүчү тарапта демпотенттүүлүк жана dedup-сактоо комбинациясы аркылуу жетишилет. транспортто HTTP "exactly-once" мүмкүн эмес.

2) Вебхук келишими: минималдуу зарыл

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').
Глобалдык тартип кепилденген эмес.
Жөнөтүүчү тарапта - ачкыч боюнча сериалдаштыруу менен кезек (бир керектөөчү/шардинг), алуучу тарапта - inbox c '(source, event_id)' жана кошумча өткөрүлбөгөн 'seq' күтүү.

Эгерде мүчүлүштүктөр оор болсо - pull-API 'GET/events бериңиз? after = checkpoint 'статусу үчүн "кууп жана текшерүү".

4) Демпотенттүүлүк жана дедупликация

Ар бир Webhook туруктуу алып 'X-Webhook-Id'.
Алуучу 'inbox (event_id)' сактайт: PK - 'source + event_id'; → no-op.
Терс таасирлери (DD/капчыкка жазуу) окуя биринчи "көрүнүш" менен гана бир жолу аткарылат.
"Эффекти бар" командалар үчүн Idempotency-Key жана Retray терезесинин убакыттын жыйынтыгы кэшин колдонуңуз.

5) Retrains, backoff жана терезелер

• Relay '5xx/timeout/connection error/409-Conflict (retryable )/429'.
• 4xx 'ге' 409/423/429 'дегенден башка (жана макулдашылган семантикада гана) ретрациялоого болбойт.
• Экспоненциалдык backoff + full jitter: 0. 5s, 1s, 2s, 4s, 8s, … чейин 'max = 10-15 мин'; TTL терезелер retrains: мисалы, 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 окуяларды (paiload, баш, ката, аракет, хэш).
Web Console/API үчүн redrive (пункту кайра жеткирүү) менен кошумча өзгөртүү endpoint/secret.
Rate-limited redrive жана batch-redrive артыкчылык менен.

7) Коопсуздук

mTLS (мүмкүн болушунча) же TLS 1. 2+.

1. 't' (timestamp) аталышынан алып, терезени текшерүү (мисалы, ± 5 мин).

8) Квоталар, rate limits жана адилеттүүлүк

Fair-Queue per tenant/subscriber: бир абонент/тенант жалпы бассейн балл эмес.
Квоталар жана чыгуучу трафик жана per-endpoint боюнча бурст-лимиттер.
жооп '429': урмат 'Retry-After', Trotlite агымы; узакка чектөөдө - degrade (окуялардын критикалык түрлөрүн гана жөнөтүү).

9) Жазылуунун жашоо цикли

Register/Verify: POST endpoint → challenge/response же out-of-band ырастоо.
Lease (каалагандай): кол чейин жарактуу 'valid _ to'; узартуу - ачык.
Secret rotation: `current_secret`, `next_secret` с `switch_at`.
Test Ping: негизги Топик алдында маршруту текшерүү үчүн жасалма окуя.
Ден соолук үлгүлөрү: latency жана TLS кароо текшерүү менен мезгилдүү HEAD/GET.

10) Схемалардын эволюциясы (окуялардын версиялары)

Окуя түрүн чыгаруу: 'payment. authorized. v1` → `…v2`.
Эволюция - additive (жаңы талаалар → MINOR версиясы API), breaking → жаңы түрү.
Схемалар реестри (JSON-Схема/Euro/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' (басылмадан 2xx чейин).
• `dedup_rate`, `out_of_order_rate`, `dlq_rate`, `redrive_success_rate`.
• `queue_depth`, `oldest_in_queue_ms`, `throttle_events`.

• Жеткирүү үлүшү ≤ 60 c (p95) - 99. 5% маанилүү окуялар үчүн.
• DLQ ≤ 0. 1% 24 саат үчүн
• Signature failures ≤ 0. 05%.

Логи/трейсинг: `event_id`, `partition_key`, `seq`, `attempt`, `endpoint`, `tenant_id`, `schema_version`, `trace_id`.

12) Жөнөтүүчүнүн референттик алгоритми

1. Иш-чараны транзакциялык outboxка жаздыруу.
2. partition_key жана seq аныктоо; кезекке коюу.
3. Уоркер ачкычын алып, суроо-талапты түзөт, кол коёт, тайм менен жөнөтөт (connect/read).
4. Качан '2xx' - жеткирилди деп таанылат, жашыруун жана seq-чекпоинтти жаздырат.
5. Качан '429/5xx/timeout' - саясатына ылайык кайра.
6. Боюнча TTL → DLQ жана алерт.

13) Референттик иштеп чыгуучу (алуучу)

1. Өтүнүчтү кабыл алуу, TLS/proto текшерүү.
2. Кол тамганы жана убакыт терезесин валидациялоо.
3. Fast ACK 2xx (жергиликтүү inbox/кезек менен синхрондуу жазуу кийин).
4. Асинхрондук воркер 'inbox' окуйт, 'event _ id' (дедуп) текшерет, керек болсо 'seq' ичинде 'partition _ key' деп тартипке салат.
5. Эффекттерди аткарат, reconcile үчүн "offset/seq чекпоинт" деп жазат.
6. Ката болгон учурда - жергиликтүү ретрациялар; "уулуу" милдеттери → жергиликтүү DLQ менен alerts.

14) Reconcile (пулл-контур)

• `GET /events? partition_key=...&after_seq=...&limit=...' - өткөрүп жибергендердин баарын берүү.
• Токен чекпоинт: 'after = opaque _ token' ордуна seq.
• Idempotent redelivery: ошол эле 'event _ id', ошол эле кол жаңы 't'.

15) Пайдалуу аталыштары жана коддору

2xx - кабыл алды (кийинчерээк бизнес-кайра иштетүү болсо да).
410 Gone - endpoint жабык (жөнөтүүчү жеткирүүнү токтотот жана жазылууну "архивге" деп белгилейт).
409/423 - ресурсту убактылуу бөгөттөө → акылга сыярлык.
429 - өтө көп → trottl жана backoff.
400/401/403/404 - конфигурациялык ката; токтотуу, билет ачуу.

16) Мультитенант жана региондор

Жеке кезек жана per tenant/endpoint чеги.
Data residency: маалымат аймагынан жөнөтүү; аркылуу 'X-Tenant', 'X-Аймак' аталыштары.
мүчүлүштүктөрдү изоляциялоо: бир абоненттин кулашы калгандарына таасир этпейт (separate pools).

17) Сыноо

Contract tests: белгиленген үлгүлөр тел/кол, validation текшерүү.
Chaos: drop/кайталанма, shuffle тартиби, тармак кечигүү, 'RST', 'TLS' -каталар.
Load: бурст-бороон, p95/p99.
Security: анти-реплика, эскирген timestamp, туура эмес сырлар, айлануу.
DR/Replay: изоляцияланган стендде DLQ массалык redrive.

18) Playbooks (runbooks)

1. Өсүү 'signature _ fail _ rate'

Сааттын жылышын, мөөнөтү өтүп кеткен "толеранттуулукту", сырлардын айлануусун текшерүү; убактылуу "dual secret" кирет.

2. Кезек эскирип баратат ('oldest _ in _ queue _ ms' ↑)

Воркерлерди көбөйтүү, критикалык топиктерди артыкчылыктуу кылуу, "ызы-чуу" түрлөрүнүн жыштыгын убактылуу төмөндөтүү.

3. Бороон '429' абоненти

Trottling жана аракет ортосунда тыныгуу кирет; окуялардын анча маанилүү эмес түрлөрүн жылдыруу.

4. Массалык '5xx'

Белгилүү бир endpoint үчүн circuit-breaker ачуу, defer режимине которуу & batch; абонентке белги.

5. DLQ толтуруу

Сын эмес жарыялоону токтотуу, төмөн RPS менен batch-redrive күйгүзүү, жазылуунун ээлерине алерттерди көтөрүү.

19) типтүү каталар

Синхрондуу оор дарылоо жооп 2xx → Retray жана кайталап.
Эч кандай кол дене/убакыт терезе → алмаштыруу/реплика аялуу.
Жок 'event _ id' жана 'inbox' → болбошу мүмкүн эмес.
Аракет "глобалдык тартип" → түбөлүк кезектерди бөгөт коюу.
jitter/чеги жок Retry → окуя күчөтүү (thundering herd).
Бардык абоненттер үчүн бирдиктүү жалпы бассейн → "ызы-чуу" баарын салат.

20) Азык-түлүктүн алдындагы чек-тизме

• Келишим: 'event _ id', 'partition _ key', 'seq', 'event _ type. vN ', кол HMAC жана timestamp.
• Жөнөтүүчү: outbox, ачкыч боюнча сериалдаштыруу, backoff + jitter, TTL, DLQ жана redrive менен retray.
• алуучу: inbox + 2xx тез жазуу; демпотенттик иштетүү; жергиликтүү DLQ.
• Коопсуздук: TLS, кол тамгалар, анти-реплика, эки жашыруун, айлануу.
• Квоталар/лимиттер: fair-queue per tenant/endpoint, урматтоо 'Retry-After'.
• Reconcile API жана текшерүү пункттары; абоненттер үчүн документтер.
• Көрүү: p95/агымдар/каталар/DLQ, 'event _ id' боюнча tracking.
• Окуялардын версиясы жана схемалардын эволюциялык саясаты.
• Playbook окуялар жана глобалдык тыныгуу/тоңдуруу "баскычы".

Корутунду

Ишенимдүү Webhucks - бул жөн гана "JSON менен POST" эмес, HTTP үстүндөгү протокол. Так келишим (ID, тартиптин ачкычы, кол), демпотенттик, jitter менен retry, адилеттүү кезек жана жакшы жөндөлгөн playbook алдын ала жана өлчөнгөн жеткирүү механизми "мыкты учурда" айланат. ат-least-once + ачкыч + reconcile тартибин куруу, жана системасы тынч тармак, жүктөө чокулары жана адам каталар аман калат.