웹 후크 및 이벤트 demempotency

TL; DR

좋은 웹 후크는 수신자의 지수 백오프 및 중복 제거가있는 적어도 한 번의 모델로 전달되는 요약 및 dempotent 이벤트 인 서명 된 (HMAC/mSL) 입니다. 봉투 ('이벤트 _ id', '유형', 'ts', '버전', '시도', '시그니처'), 시간 창 (느낌표 5 분), 응답 코드, 배상, DLQ 및 상태 끝점에 동의하십시오.

1) 역할 및 전달 모델

Sender (you/provesser): 이벤트, 부호, 최대 2xx 전달을 시도하고 3xx/4xx/5xx (명시 적 "수락 금지" 제외) 에서 재 트레이션을 시도하고 DLQ를 리드하고 API를 재생합니다.
수신자 (파트너/귀하의 서비스): 서명/시간 창을 확인하고, dedup 및 dempotent 처리를 수행하고, 올바른 코드로 응답하고, '이벤트 _ id' 로/상태 및/ack 재생을 제공합니다.

보증: 적어도 한 번은. 수신자는 중복 및 재정렬을 처리 할 수 있어야합니다.

2) 이벤트의 봉투

json
{
"event_id": "01HF7H9J9Q3E7DYT5Y6K3ZFD6M",
"type": "payout.processed",
"version": "2025-01-01",
"ts": "2025-11-03T12:34:56.789Z",
"attempt": 1,
"producer": "payments",
"tenant": "acme",
"data": {
"payout_id": "p_123",
"status": "processed",
"amount_minor": 10000,
"currency": "EUR"
}
}

필요한 필드는 '이벤트 _ id', '유형', '버전', 'ts', '시도' 입니다.
진화 규칙: 필드 추가; 새 '버전' 으로 만 유형을 삭제/변경하십시오.

3) 보안: 서명 및 구속력

3. HMAC 서명 1 개 (기본 권장 사항)

X-Signature: v1=base64(hmac_sha256(<secret>, <canonical>))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF7...

<timestamp>\n<method>\n<path>\n<sha256(body)>

• 복근 (현재- 'X- 타임 스탬프')
• 이전에 처리하지 않은 'X-Event-ID' (dedup)
• 'X-Signature' 일치 (시간 안전 비교)

3. 2 해결. 측정

매우 민감한 웹 후크를위한 mTLS.
IP/ASN 허용 목록.
웹 후크가 콜백을 시작하는 경우 발신자가 제한하는 DPoP (옵션).

4) 이념과 중복 제거

4. 1 이벤트 demempotency

• TTL의 이벤트 _ id 'in demempotent 캐시 (KV/Redis/DB) 를 24-72 시간 이상 저장합니다.
• 다시 반환하기 위해 처리 결과 (성공/오류, 아티팩트) 를 저장합니다.

4. 2 명령 demempotency (콜백)

웹 후크가 클라이언트가 API를 당기도록 강요하면 (예: "지불 확인") REST 통화에서 'Idempotency-Key' 를 사용하고 결과를 서비스 측에 저장하십시오 (정확히 한 번 결과).

key: idempotency:event:01HF7...
val: { status: "ok", processed_at: "...", handler_version: "..." }
TTL: 3d

5) Retrai 및 백오프

• '5, 15, 30, 1m, 2m, 5m, 10m, 30m, 1 시간, 3 시간, 6 시간, 12 시간, 24 시간' (매일 최대 N 일)

• 2xx-성공, 배상 중지.

• '400/401/403/404/422' -서명/형식이 괜찮은 경우 재생할 수 없습니다 (클라이언트 오류).
• '429' - 'Recuted-After' 또는 백오프에 의한 retrayim.
• 5xx/네트워크-retrayim.

데이터 헤더: '사용자 에이전트', 'X-Webhook-Producer', 'X-Atteem'.

6) 수신자 측 처리

pseudo verify_signature()
if abs(now - X-Timestamp) > 300s: return 401

if seen(event_id):
return 200 // идемпотентный ответ

begin transaction if seen(event_id): commit; return 200 handle(data)       // доменная логика mark_seen(event_id)    // запись в KV/DB commit return 200

거래성: "보이는" 레이블은 고장시 이중 처리를 피하기 위해 작업 (또는 결과를 수정 한 후) 의 영향으로 원자 적으로 설정해야합니다.

7) 주문 및 스냅 샷 보장

주문이 보장되지 않습니다. '데이터' 에서 'ts' 및 도메인 'seq '/' 버전' 을 사용하여 관련성을 확인하십시오.
긴 지연/손실-발신자의 추가/재생 및 수신자의 재생 (시간/ID 창에서 스냅 샷 및 델타 얻기).

8) 상태, 재생 및 DLQ

8. 보내기 엔드 포인트 1 개

'POST/webhooks/replay' - '이벤트 _ id' 목록 또는 시간 창 별.
'GET/webhooks/이벤트/: id' -소스 패키지 및 시도 내역을 표시하십시오.
DLQ: "죽은" 이벤트 (리트레이 제한이 소진되었습니다) → 별도의 스토리지, 경고.

8. 수신자 끝점 2 개

'GET/webhooks/상태/: 이벤트 _ id' - 'seel = 참/거짓', '처리 된 _ at', '핸들러 _ 버전'.
'POST/webhooks/ack' - (옵션) DLQ의 수동 처리 확인.

9) 오류 계약 (수신자 응답)

http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Retry-After: 120
X-Trace-Id: 4e3f...

{
"error": "invalid_state",
"error_description": "payout not found",
"trace_id": "4e3f..."
}

권장 사항: 항상 명확한 코드와 가능한 경우 '재시도 후' 를 반환합니다. 자세한 보안 정보를 반환하지 마십시오.

10) 모니터링 및 SLO

• 배달 p50/p95, 성공률, 재 트레이/이벤트, 드롭 레이트 DLQ, 2xx/4xx/5xx 공유, 최대 2xx 지연 창.

• 실패율 (서명/시간), dup-rate, 대기 시간 처리기 p95, 5xx 확인.

• 배송: 99 이상입니다. 이벤트의 9% 는 2xx <3 c p95를받습니다 (첫 번째 성공적인 시도 후).
• 암호화 검증: 시그니처 유효성은 2-5 ms p95입니다.
• 데드 업: 0 반복 효과 (도메인 레벨에서 정확히 한 번 결과).

11) 데이터 보안 및 개인 정보

웹 후크 본체에서 PAN/PII를 전송하지 마십시오. ID를 사용한 다음 승인 된 API에 대한 세부 정보를 얻으십시오.
통나무의 마스크 민감한 필드; TTL을 사용하여 이벤트 본문을 최소한으로 저장하십시오.
DLQ를 저장하고 재생합니다.

12) 수정 및 호환성

'버전' (봉투) 및 운송 중 버전: '/webhooks/v1/payment '.
새로운 필드는 선택 사항입니다. 제거 - '일몰' 기간 후에 만.
자동 점검을 위해 기계에서 읽을 수있는 변경 로그의 변경 사항을 문서화하십시오.

13) 테스트 사례 (UAT 체크리스트)

• 동일한 '이벤트 _ id' → 하나의 효과와 '200' 을 복제합니다.
• 시그니처: 올바른 키, 잘못된 키, 오래된 키 (회전), 'X-Timestamp' 창 밖으로.
• 백오프: 수신자는 '429' 와 함께 'Redection-After' → 정확한 일시 정지를 제공합니다.
• 주문: 이벤트 '... 처리 된 '이전'... '→ 올바른 처리/대기.
• 효과와 'mark _ seen' → 원자/반복 사이의 수신기에서의 데이터베이스 실패.
• DLQ 및 수동 재생 → 성공적인 배송.
• 질량 "폭풍" (공급자는 팩을 보냅니다) → 손실없이 한계는 치명적이지 않습니다.

14) 미니 스 니펫

pseudo body = json(event)
canonical = ts + "\n" + "POST" + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
headers = {"X-Timestamp": ts, "X-Event-Id": event.event_id, "X-Signature": "v1="+sig}
POST(url, body, headers)

pseudo assert abs(now - X-Timestamp) <= 300 assert timingSafeEqual(hmac(secret, canonical), sig)

if kv.exists("idemp:"+event_id): return 200

begin tx if kv.exists("idemp:"+event_id): commit; return 200 handle(event.data)        // доменная логика kv.set("idemp:"+event_id, "ok", ttl=259200)
commit return 200

15) 빈번한 오류

중복 제거 → 반복 효과 (이중 수리/지불) 가 없습니다.
타임 스탬프/창 → 재생 취약점이없는 서명.
모든 파트너에게 하나의 HMAC 비밀을 저장합니다.
결과를 수정하기 전에 '200' 응답 → 충돌 이벤트 손실.
답변/로그에 대한 보안 정보를 "세척" 합니다.
DLQ/재생 부족-사고를 해결할 수 없습니다.

16) 구현 치트 시트

보안: HMAC v1 + 'X-Timestamp' + 'X-Event-ID', 창이 5 분; (PHP 3 = 3.0.6, PHP 4)

이벤트 _ id ',' 유형 ',' 버전 ',' ts ',' 시도 ',' 데이터 '.
배송: 적어도 한 번은 지터, '재생 후', DLQ + 재생 API를 사용한 백오프.
이념성: KV- 캐시 24-72 h, 효과의 원자 고정 + 'mark _ seen'.
관찰 가능성: 전달, 서명, 중복 메트릭; trace _ id.
문서: 버전, 응답 코드, 예, UAT 체크리스트.

요약 다시 시작

영구적 인 웹 후크는 서명 된 봉투, 적어도 한 번은 배달 및 demmpotent 가공의 세 가지 고래에 내장되어 있습니다. 계약을 공식화하고, HMAC/mTLS와 시간 창을 활성화하고, retrai + DLQ를 구현하고, 재생하고, demempotent 라벨을 저장하고, 효과를 원자 적으로 캡처합니다. 그런 다음 네트워크 오류, 로드 피크 및 드문 "운명의 복제본" 으로도 이벤트를 신뢰할 수 있습니다.