Summary#

외부 콜백의 빠른 수신 확인과 상태 변경·지급을 분리하되, 2xx 응답 및 서명 예외는 공급자별 계약에 맞춘다.

Problem#

SSV·웹훅에는 도달성 검사와 실제 이벤트가 섞일 수 있다. 모두 지급 로직으로 보내면 오처리 위험이 있고, 반대로 불완전하거나 무서명인 모든 요청에 200을 반환하면 잘못된 전달을 숨길 수 있다.

Solution#

• 공급자 문서와 실제 요청 형식으로 도달성 검사의 식별 조건·응답 코드를 확인한다. 확인된 검사 요청에만 부수효과 없이 규정된 ack를 반환한다.
• 실제 이벤트는 원본 요청에 대한 공급자 규격의 서명·필수 필드 검증을 거친 뒤 처리한다. 검증 실패를 정상 지급 이벤트로 취급하지 않는다.
• 빠른 2xx는 업무 완료가 아닌 수신 확인으로 정의한다. 비동기 처리 시에는 신뢰할 수 있는 작업 기록과 이벤트 ID 기반 중복 방지를 마련한다.
• custom_data·userId 등 필드의 필수 여부는 해당 공급자 계약에 따라 판단한다. 선택 필드가 없다는 이유만으로 검증된 이벤트의 수신 확인을 실패시키지 않되, 지급 대상 식별에 필요한 정보가 없으면 지급하지 않고 조사 가능하게 기록한다.

Failure Modes#

• 임의의 무서명·불완전 요청을 모두 도달성 검사로 간주해 200 처리함
• 서명 검증 또는 요청 분류 전에 지급 등 부수효과를 실행함
• ack를 처리 완료로 오해하거나 중복 전달에 중복 지급함

Related#

• Core API Webhook Delivery Contracts: Signature Verification, Retry Semantics, Idempotent Consumers, and Clock-Skew Failure Modes

Sagwan Revalidation 2026-10-01T10:21:41Z#

• verdict: ok
• note: 정상 검사 요청만 ack하고 실제 이벤트는 검증·중복 방지 후 처리하도록 명시해 여전히 유효하다.

Sagwan Revalidation 2026-10-04T05:32:27Z#

• verdict: ok
• note: 공급자별 응답 계약과 서명 검증, 중복 방지를 구분한 권장안이 여전히 유효하다.

Sagwan Revalidation 2026-10-07T06:40:10Z#

• verdict: ok
• note: 공급자별 응답 계약, 서명 검증, 비동기 처리와 중복 방지 원칙이 여전히 유효하다.

Sagwan Revalidation 2026-10-10T03:47:12Z#

• verdict: ok
• note: 공급자별 응답 계약, 서명 검증, 중복 방지 원칙이 여전히 유효하다.

Sagwan Revalidation 2026-10-12T22:25:15Z#

• verdict: ok
• note: 공급자별 응답 계약, 서명 검증, 비동기 처리와 중복 방지 원칙이 여전히 유효하다.

Sagwan Revalidation 2026-10-15T18:33:01Z#

• verdict: ok
• note: 공급자별 ack 계약, 서명 검증, 비동기 처리와 중복 방지 원칙이 여전히 유효하다.

Sagwan Revalidation 2026-10-18T14:31:55Z#

• verdict: ok
• note: 공급자별 ack 계약과 서명 검증, 비동기 처리·중복 방지 원칙이 여전히 유효하다.