Webhooks: 명세
원시 바디에 대한 HMAC으로 서명된 아웃바운드 웹훅, 안정적인 전달 식별자, 제한된 재시도 후 데드레터, 시계 오차 허용 타임스탬프, 콜백 URL에 비밀 정보 없음.
패키지 상태: 참조 컨텍스트로서 인간 검토 준비 완료. 계약과 테스트 시나리오는 완성되었으나, 이를 통과한 채택 구현체가 있다고 주장하지는 않음.
결정 사항
아웃바운드 통합 이벤트는 서명된 HTTP POST 바디로 전달됩니다. 각 전달은 도메인 이벤트 ID와 구분되는 내구성 있는 식별자를 가지므로 재시도 시 동일한 전달로 유지됩니다. HMAC은 전송될 원시 바이트를 키 ID와 발신자 타임스탬프에 바인딩하여 커버합니다. 비밀은 쿼리 파라미터에 절대 나타나지 않습니다. 재시도는 명명된 스케줄 프로필과 라벨이 붙은 지터를 따르며, 이후 데드레터로 들어갑니다. 전달은 적어도 한 번 이상 보장되며, 수신자는 전달 ID로 중복 제거를 수행합니다.
범위
- 이벤트가 아웃박스에 커밋된 후 워커의 시도.
- 서명 헤더, 타임스탬프 오차, 키 회전 식별자, 재시도 제한, 데드레터, 종료 상태.
이 블록 밖
- 도메인 트랜잭션과 원자적 아웃박스 쓰기 (관련 아웃박스 패키지).
- 파트너가 인바운드 서명을 검증하는 방법 (관련 인바운드 서명 패키지).
계약
- 모든 HTTP 시도는 안정적인 전달 ID, 증가하는 시도 번호, 키 ID, 타임스탬프, 정확한 바디 바이트에 대한 HMAC을 포함합니다.
- 콜백 URL에는 서명 비밀, 토큰, 테넌트 자격 증명이 포함되지 않으며, 자격 증명은 헤더나 구독 레코드에 존재합니다.
- 재시도 가능한 파트너 상태는 스케줄 프로필을 따르며, 재시도 불가능한 클라이언트 상태는 추가 시도 없이 종료됩니다.
- 프로필 최대 시도 후 상태는 데드레터되고 종료 실패 상태가 되며, 운영자 재생 시 새로운 전달 ID가 할당됩니다.
- 재생 창 밖의 타임스탬프는 동일 전달에 대해 새로운 식별자로 전송되지 않으며, 워커는 재시도 시 현재 타임스탬프로 서명하거나 시도를 만료로 표시합니다.
- 중복 워커 깨우기는 동일한 전달 ID를 재사용하며 두 번째 인플라이트 패밀리를 생성하지 않습니다.
구현 지침
- 워커가 충돌 후 재개할 수 있도록 아웃박스를 통해 게시합니다. 서명 전에 바디를 한 번 정규화하고, 서명과 전송 사이에 재직렬화하지 않습니다.
- 이전 키가 인플라이트 재시도에 유효한 동안 새 키 ID를 광고하여 키를 회전합니다.
실패 처리 및 안전장치
- 전송 타임아웃은 재시도 가능하며 시도를 소모합니다. 구독 허용 목록에 없는 호스트로의 리디렉션은 종료 실패 상태입니다.
- 서명 자료 누락은 서명되지 않은 바디를 보내지 않고 운영자 결함으로 시도를 실패 처리합니다.
검증 및 운영
- 서명된 바이트가 전송된 바디와 동일하며 URL 쿼리에 비밀이 없는지 확인합니다. 전송 후 확인 전 워커를 혼란 상태로 만들고 하나의 전달 ID에 두 번의 시도가 있음을 증명합니다.
이 패키지 내 실행 가능한 예제들은 픽스처 및 수용 계약입니다. 컬렉션 루트에서
python tools/validate.py를 실행하여 패키지 구조와 메타데이터를 확인한 후,
대상 저장소에서 시나리오를 구현하고 실행하세요.
채택 가정
example.yaml의 이름과 숫자 값은 채택 프로필이며 보편적 기본값이 아닙니다.- 채택 팀은 행위자, 데이터 클래스, 오류 어휘, 소유권을 자사 시스템에 매핑해야 합니다.