Webhook 서명 확인 및 멱등성

이 페이지는 다음과 같습니다 Agent Java SDK WEBHOOKS.md 커밋 fa6c7b6. 이는 문서 전용 업데이트입니다. 경고 도우미 메서드가 포함된 새로운 SDK 아티팩트가 출시되지 않았습니다.

네 가지 이벤트 유형 모두 하나의 판매자 콜백 URL 을 사용하며 본문 event에 의해 전달됩니다. 보다 Webhook 이벤트 및 청산 경고 이벤트 필드 및 페이로드 예시.

Webhook 헤더

timestamp + nonce + rawBody

이벤트 멱등성

판매자 및 environment 범위 내에서 비즈니스 처리를 통해 원자적으로 중복 제거를 유지합니다. 서로 다른 notificationId 값은 독립적인 FIRST / UPGRADE / REMINDER 알림을 식별합니다. 사용자, 에피소드 또는 eventType별로 그룹화하여 알림을 삭제하지 마세요. 빈 멱등성 키는 중복 제거에 사용할 수 없습니다. SDK는 도우미 키만 반환합니다. 비즈니스 데이터를 유지하거나 처리하지 않습니다. 동일한 정체성을 다른 신체와 충돌로 기록합니다. 처리된 본문을 덮어쓰지 마십시오.

서명 확인 및 수신

판매자 API 비밀을 사용하여 HMAC-SHA256 timestamp + nonce + rawBody의 16진수 서명을 계산합니다. 원래 수신된 바이트를 확인하십시오. 먼저 JSON 형식을 지정하거나, 필드 이름을 바꾸거나, 본문을 다시 직렬화하지 마세요.

먼저 서명을 확인한 후 시간대(권장 ±300초), 가맹점, 환경을 확인하세요. 다음으로 멱등성 ID를 추출하고 알림을 안정적으로 처리합니다. 진단을 위해 알 수 없는 이벤트 값을 보존합니다. 절대 펀드 성공으로 해석하지 마세요. 확인 도우미는 기간, 소유권 또는 지속적인 중복 제거 확인을 수행하지 않습니다.

처리를 완료하거나 동일한 중복 항목을 확인한 후 HTTP 2xx를 반환합니다. 실패 시 2xx가 아닌 값을 반환합니다. 경고 발신자에게는 5초의 HTTP 시간 제한이 있으며 최대 8번의 시도가 가능합니다. 재시도 시 고정된 본체가 유지됩니다. 서명 타임스탬프와 nonce만 변경됩니다. 신뢰할 수 있는 승인 후 즉시 응답합니다. 장기 실행 비즈니스 작업은 판매자 자신의 지속적인 작업을 사용할 수 있습니다.

판매자 알림은 사용자의 온라인 상태에 의존하지 않습니다. 플랫폼 사용자 푸시는 오프라인 재생 없이 온라인으로 최선을 다해 전달됩니다. 1단계에는 알림 받은 편지함이 없습니다.

성공적인 응답 및 재시도 중지

자금 콜백 및 청산 경고는 HTTP 상태 코드만 사용하여 배송 성공 여부를 결정합니다. 발신자는 응답 본문 code, success, result 또는 message를 해석하지 않으며 고정된 OK / success 응답이 필요하지 않습니다.

응답 본문은 비어 있거나 텍스트 또는 JSON일 수 있습니다. 예시 result 필드는 프로토콜 요구사항이 아니라 판매자를 위한 정보 제공용입니다. 202 Accepted 또한 플랫폼 재시도를 중지하므로 단순히 메모리 내 비동기 작업을 시작하는 것이 아니라 판매자의 영구 작업 대기열에 알림을 안정적으로 저장한 후에만 반환합니다.

성공적인 응답 예시

비즈니스 처리가 완료되거나 알림이 판매자의 대기 대기열에 안정적으로 저장된 후:

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"RECEIVED"}

응답 본문이 필요하지 않은 경우:

HTTP/1.1 204 No Content

동일한 본문으로 이미 처리된 알림의 경우 중복 비즈니스 처리를 건너뛰고 계속 2xx를 반환합니다.

HTTP/1.1 200 OK
Content-Type: application/json
{"result":"DUPLICATE"}

실패 대응 예시

데이터베이스를 일시적으로 사용할 수 없고 판매자가 처리를 완료하지 않았거나 알림을 안정적으로 저장하지 않은 경우 플랫폼이 다시 시도할 수 있도록 2xx가 아닌 값을 반환하세요.

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
{"result":"FAILED","message":"temporary storage failure"}

비즈니스 데이터 또는 성공적인 중복 제거 기록을 업데이트하지 않고 잘못된 서명을 거부합니다.

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"result":"INVALID_SIGNATURE"}

이러한 응답 본문은 재시도 결정을 변경하지 않습니다. 401 또는 409로 인해 재시도가 영구적으로 중지될 것이라고 기대하지 마세요. 서명, 알림 내용 또는 판매자 구성을 조사합니다.

잘못된 예: 다음 응답은 여전히 ​​성공적인 전달로 간주됩니다. 플랫폼은 success:false 때문에 재시도하지 않습니다.

HTTP/1.1 200 OK
Content-Type: application/json
{"success":false,"code":500,"message":"processing failed"}

프레임워크 또는 전역 예외 처리기가 비즈니스 실패를 HTTP 200으로 래핑하는 경우 콜백 엔드포인트에서 올바른 실패 상태를 명시적으로 설정합니다.

안정적인 승인 및 중복 전달

권장 순서: 서명 확인 및 시간/가맹점/환경 확인 → 멱등성 ID 추출 → 거래 내 비즈니스 데이터 및 중복 제거 성공 기록 처리 또는 대기 중인 작업을 안정적으로 저장 → 커밋 성공 후 200/204 반환. 2xx를 반환하거나 성공적인 데이터베이스 쓰기 전에 처리된 알림을 표시하지 마세요.

판매자 처리가 성공한 후에도 중복 배송이 계속 발생할 수 있습니다. 응답이 손실되거나 플랫폼이 2xx를 수신했지만 유지하지 못할 수 있습니다SUCCESS. HTTP 콜백은 일회성 전달을 보장하지 않습니다. 판매자 및 environment 범위 내에서 중복 제거를 유지합니다. 자금 사용 orderType:orderId:targetStatus; 경고에는 liquidation.warning:notificationId를 사용합니다. 이미 처리된 동일한 본문의 경우 자금을 적립하거나 알림을 다시 발행하지 않고 2xx를 반환합니다. 다른 본문을 가진 동일한 ID의 경우 충돌을 기록하고 non-2xx를 반환합니다. 원본 레코드를 덮어쓰지 마십시오.

승인 성공은 가맹점이 알림을 수신/처리했다는 의미이지, 자금 운용이 성공했다는 의미는 아닙니다. targetStatus=FAILED로 유효한 자금 알림을 기록한 후 2xx도 반환합니다. 주문 실패는 알림 확인을 거부하는 이유가 되지 않습니다.

자금 및 환경 경계

원래 계약 이전 webhook 및 queryOrder 흐름은 자금 조달에 자동으로 적용되지 않습니다. queryWalletTransfer 및 원래 주문 환경을 사용하여 자금 조달 작업을 확인합니다. 자금은 status를 사용합니다. 원래 계약 이전 응답은 orderStatus를 사용합니다. 성공적인 HTTP 응답 또는 code=0 자체만으로는 자금 이동이 입증되지 않습니다.

명시적인 시뮬레이션 계약 이전 알림에는 environment=SIMULATED이 포함됩니다. 원시 본문을 먼저 확인한 후 저장된 로컬 비즈니스 주문을 기준으로 사용자, 금액, 주문 ID 및 환경을 확인합니다.

자금 회수 가이드 · 환경가이드