웹 후크 배송 보증
웹 후크는 HTP (S) 를 통한 비동기 시스템 대 가입자 알림입니다. 네트워크는 신뢰할 수 없습니다. 응답이 손실되고 패킷이 중복되거나 순서가 잘못되었습니다. 따라서 배송 보증은 "TCP를 통한" 것이 아니라 웹 후크 프로토콜 및 도메인 demempotency 수준으로 구축됩니다.
주요 목표는 키별로 (필요한 경우) 최소한 한 번 주문한 배송을 제공하고, 가입자에게 dempotent 처리를위한 자료를 제공하고 복원을위한 조정 도구를 제공하는 것입니다.
1) 보증 수준
최선의 노력-레트라없이 일회성 시도. "중요하지 않은" 이벤트에만 허용됩니다.
최소한 한 번 (권장) -중복 및 순서가 맞지 않는 것이 가능하지만 가입자가 합리적인 시간 내에 사용할 수있는 경우 이벤트가 제공됩니다.
가입자/발신자 측에서 demempotency와 dedup Storage의 조합으로 효과적으로 정확하게 한 번 (효과 수준) 달성되었습니다. "정확하게 한 번" TP 전송이 불가능합니다.
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/jsonjson
{
"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').
글로벌 질서는 보장되지 않습니다.
발신자 쪽에는 키별로 직렬화 된 대기열 (하나의 소비자/샤딩) 이 있으며, 수신자 쪽에는 '(소스, 이벤트 _ id)' 가있는받은 편지함이 있으며 선택적으로 누락 된 'seq' 를 기다립니다.
간격이 중요한 경우-풀 API 'GET/이벤트를 제공하십니까? "따라 잡기 및 상담" 에 대한 = 체크 포인트 '.
4) 이념과 중복 제거
각 웹 후크에는 안정적인 'X-Webhook-ID' 가 있습니다.
수신자는 '받은 편지함 (이벤트 _ id)' 을 저장합니다. (PHP 3 = 3.0.6, PHP 4)
부작용 (데이터베이스/지갑에 쓰기) 은 이벤트가 처음 "보이는" 경우에만 한 번만 수행됩니다.
효과가있는 명령의 경우 다시 트레이 창 기간 동안 Idempotency-Key 및 결과 캐시를 사용하십시오.
5) Retrai, 백오프 및 창문
재 트레이 정책 (참조):- '5xx/타임 아웃/연결 오류/409-충돌 (재시도 가능 )/429' 로 재교육합니다.
- '409/423/429' (일관된 의미론 만 있음) 를 제외하고 '4xx' 를 철회하지 마십시오.
- 지수 백오프 + 풀 지터: 0. 5s, 1s, 2s, 4s, 8s,... 최대 'max = 10-15 min'; TTL 재 트레이 창: 예를 들어 72 시간
- 수신자로부터 '재생 후' 를 존중하십시오.
- "이벤트가 전달되지 않은 것으로 인식" 하고 DLQ로 이전하는 공통 마감일이 있습니다.
yaml retry:
initial_ms: 500 multiplier: 2.0 jitter: full max_delay_ms: 900000 ttl: 72h retry_on: [TIMEOUT, 5xx, 429]6) DLQ 리드라이브
DLQ- 전체 메타 정보 (페이로드, 헤더, 오류, 시도, 해시) 가있는 유독 또는 TTL 만료 이벤트의 "묘지".
엔드 포인트/비밀 편집 옵션으로 리드라이브 (포인트 재전달) 를위한 웹 콘솔/API.
속도 제한 재구동 및 배치 재 구동 우선 순위.
7) 안전
mTLS (가능한 경우) 또는 TLS 1. 2+.
바디 서명 (테넌트/엔드 포인트 당 비밀이있는 HMAC). 검증:1. (PHP 3 = 3.0.6, PHP 4)
8) 쿼타, 금리 제한 및 지분
세입자/가입자 당 Fair-Queue: 한 가입자/세입자가 전체 풀의 점수를 얻지 못합니다.
나가는 트래픽 및 종점에 대한 쿼타 및 버스트 제한.
'429' 에 대한 반응: 명예 'Redure-After', 트롤 스트림; 장기 제한-저하 (중요한 이벤트 유형 만 전송).
9) 구독 수명주기
등록/확인: POST 엔드 포인트 → 챌린지/응답 또는 대역 외 확인.
임대 (선택 사항): 서명은 '유효한 _ to' 까지 유효합니다. 연장 - 명시 적.
비밀 회전: '현재 _ 비밀', '다음 _ 비밀' ° '스위치 _ at'.
테스트 핑: 주요 주제를 켜기 전에 경로를 테스트하는 인공 이벤트.
건강 샘플: 대기 시간 및 TLS 프로파일 확인이 포함 된주기적인 HEAD/GET.
10) 체계의 진화 (이벤트 버전)
이벤트 유형 확인: '결제. 승인 된. v1 '→'... v2 '.
진화 - 첨가제 (새로운 필드 → MINOR API 버전), → 새로운 유형을 깨뜨립니다.
스키마 레지스터 (JSON-Schema/Avro/Protoguy) + 제출 전에 자동 검증.
본문의 'X-Event-Type' 헤더와 'schema _ version' 필드가 모두 필요합니다.
11) 관찰 및 SLO
메트릭 (유형/테넌트/가입자 별):- 'delivery _ total', '2xx/4xx/5xx _ rate', 'times _ rate', 'sign _ fail _ rate'.
- '시도 _ avg', 'p50/p95/p99 _ delivery _ latency _ ms' (2xx에 게시).
- 'dedup _ rate', 'out _ of _ order _ rate', 'dlq _ rate', 'redrive _ success _ rate'.
- (PHP 3 = 3.0.6, PHP 4)
- 배송 비율은 약 60 초 (p95) -99입니다. 중요한 이벤트의 경우 5%.
- DLQ 지정 0. 24 시간 동안 1%
- 시그니처 실패 05%.
계정: '이벤트 _ id', '파티션 _ key', 'seq', '시도', '엔드 포인트', '테넌트 _ id', '스키마 _ 버전', 'trace _ id'.
12) 보내기 참조 알고리즘
1. 트랜잭션 아웃박스에 이벤트를 작성하십시오.
2. (PHP 3 = 3.0.6, PHP 4) 대기열.
3. 작업자는 키를 사용하여 요청을 작성하고 표시하며 타임 아웃과 함께 보냅니다 (연결/읽기).
4. '2xx' 를 사용하면 전달 된대로 인식하고 대기 시간을 수정하고 체크 포인트를 수정하십시오.
5. '429/5xx/타임 아웃' 을 사용하면 정책에 따라 후퇴합니다.
6. TTL → DLQ 및 경고로.
13) 참조 프로세서 (수신기)
1. 요청을 수락하고 TLS/proto를 확인하십시오.
2. 서명 및 시간 창 검사
3. 빠른 ACK 2xx (로컬받은 편지함/큐에 동기식 쓰기 후).
4. 비동기 작업자는 '받은 편지함' 을 읽고 '이벤트 _ id' (할아버지) 를 확인하며 필요한 경우 'seq' inside 'partition _ key' 로 주문합니다.
5. 효과를 수행하고 조정을 위해 "오프셋/seq 체크 포인트" 를 작성하십시오.
6. 오류가있는 경우-로컬 배송; "유독 한" 작업 → 경고가있는 로컬 DLQ.
14) 화해 (풀 루프)
"뚫을 수없는" 사건의 경우:- 'GET/이벤트? (PHP 3 = 3.0.6, PHP 4) -모든 놓친 것을주기 위해.
- 토큰 체크 포인트: seq 대신 'after = opaque _ token'.
- 이념적 재전달: 동일한 '이벤트 _ id', 새로운 't' 의 동일한 서명.
15) 유용한 제목 및 코드
2xx-허용됩니다 (비즈니스 처리 후에도).
410 Gone-종점이 닫힙니다 (발신자는 배송을 중단하고 구독을 "보관" 으로 표시).
409/423-리소스 → 리트레이의 임시 차단이 합리적입니다.
429-너무 자주 → 스로틀 및 백오프.
400/401/403/404 - 구성 오류; 레트라이를 멈추고 티켓을 엽니 다.
16) 멀티 테넌트 및 지역
임차인/엔드 포인트 당 개별 대기열 및 제한.
데이터 레지던트: 해당 지역에서 데이터 전송; 엔드 투 엔드 헤더 'X-Tenant', 'X-Region'.
실패 격리: 한 가입자의 추락은 나머지 (별도의 풀) 에 영향을 미치지 않습니다.
17) 테스트
계약 테스트: 신체/서명의 고정 된 예, 검증 검사.
혼돈: 드롭/복제, 셔플 순서, 네트워크 지연, 'RST', 'SL' 오류.
하중: 폭풍, p95/p99 측정.
보안: 재생 방지, 오래된 타임 스탬프, 잘못된 비밀, 회전.
DR/재생: 격리 된 스탠드에서 DLQ에서 대량 재구동.
18) 플레이 북 (런북)
1. 'sign _ fail _ rate' 성장
시계 드리프트, 만료 된 '허용 오차', 비밀의 회전을 확인하십시오. "이중 비밀" 을 일시적으로 활성화하십시오.
2. 대기열이 노화되고 있습니다 ('가장 오래된 _ in _ queu _ ms' TP)
작업자를 늘리고 중요한 주제의 우선 순위를 정하고 "잡음" 유형의 빈도를 일시적으로 줄입니다.
3. 가입자의 폭풍 '429'
스로틀 링을 사용하고 시도 사이에 일시 중지; 덜 중요한 이벤트 유형을 이동합니다.
4. 질량 '5xx'
특정 엔드 포인트를위한 개방 회로 차단기, 연기 및 배치로 전환; 가입자에게 신호를 보냅니다.
5. 포퓰레이션 DLQ
중요하지 않은 게시를 중지하고 RPS가 낮은 배치 재구성을 활성화하고 구독 소유자에게 경고를 제기하십시오.
19) 전형적인 오류
2xx 응답에 대한 동기식 무거운 처리 → 재처리 및 중복.
본문/시간 창 서명 → 대체/재생 취약점이 없습니다.
'이벤트 _ id' 및 '받은 편지함' → 이 없으면 demmpotent가 될 수 없습니다.
"전역 질서" 에 대한 시도 → 영원한 대기열 잠금.
지터/제한이없는 후퇴 → 사고 강화 (천둥 무리).
모든 가입자를위한 단일 공통 풀 → "잡음" 은 모든 사람을 배치합니다.
20) 사전 판매 점검표
- 계약: '이벤트 _ id', '파티션 _ key', 'seq', '이벤트 _ 유형. vN ', HMAC 서명 및 타임 스탬프.
[Sender]: 아웃 박스, 키로 직렬화, 백오프 + 지터, TTL, DLQ 및 재구동 기능이있는 배열.- 수신자: 받은 편지함에 빠르게 쓰기 + 2xx; demmpotent 치료; 로컬 DLQ.
- 보안: TLS, 서명, 재생 방지, 듀얼 비밀, 로테이션.
- 쿼터/제한: 임차인/엔드 포인트 당 공정 대기열, '재시도 후' 존중.
- 조정 AP 및 체크 포인트; 가입자를위한 문서.
- 관찰 가능성: p95/스레드/오류/DLQ, '이벤트 _ id' 추적.
- 이벤트 버전 지정 및 스키마 진화 정책.
- 인시던트 플레이 북 및 글로벌 일시 정지/제상 버튼.
결론
트러스트 웹 후크는 "JSON의 POST" 뿐만 아니라 HTTP의 프로토콜입니다. "명확한 계약 (ID, 주문 키, 서명), demotency, 지터가있는 retray, 공정한 대기열 및 잘 정리 된 플레이 북은 최상의 경우를 예측 가능하고 측정 가능한 전달 메커니즘으로 바꿉니다. 최소 한 번 + 키 주문 + 조정을 빌드하면 시스템이 네트워크에서 차분하게 살아남고 피크를로드하고 인적 오류가 발생합니다.