암호화폐 결제 웹훅 보안: 서명, 재전송 공격, 재시도

RSA-SHA256, 서명된 원본 바이트, 재전송 공격 방지, 영속적 멱등성, 올바른 재시도 처리로 암호화폐 결제 웹훅을 안전하게 구현하는 실무 가이드입니다.

게시일 , 수정일

차분한 운영 데스크 위 노트북, 자물쇠, 가지런히 감긴 케이블로 표현한 암호화폐 결제 웹훅 보안

암호화폐 결제 웹훅을 안전하게 처리하려면 요청을 신뢰하기 전에 서명을 검증하고, 결제를 저장된 주문에 연결하며, 그 결과를 정확히 한 번만 반영해야 합니다. Suawave에서는 RSA-SHA256으로 x-ca-signature를 검증하고 서명된 원본 바이트를 보존하며 이벤트 UUID를 영속적으로 저장해 중복을 제거합니다. 이벤트를 영속적 처리 경로에 반영한 뒤에만 HTTP 200과 *ok*를 반환하세요.

웹훅 핸들러는 결제 기록을 쓰는 코드입니다. 정상 요청이 두 번 도착하거나, 두 입금이 동시에 도착하거나, 데이터베이스 커밋 직후 프로세스가 종료되어도 올바르게 동작해야 합니다. 서명 검증은 이 작업의 일부만 담당합니다.

1. 서명을 확인하기 전에 원본 바이트 보존하기

Suawave 공개 콜백은 PKCS#1 v1.5 패딩을 사용하는 base64 RSA-SHA256 서명을 사용합니다. HTTPS로 GET /pubkey/를 호출해 PKIX PUBLIC KEY PEM을 가져오세요. 2048비트 이상의 RSA 키인지 검증한 뒤 캐시합니다. 공개 검증기에는 공유 HMAC secret이나 서명용 개인 키 접근 권한이 필요하지 않습니다.

서명 대상 메시지는 콜백 전송 방식에 따라 달라집니다.

콜백 전송 방식 서명 대상 메시지 흔한 연동 실수
기본 GET 원래 쿼리 순서를 유지한 전체 외부 URL 파라미터 정렬 또는 재인코딩
post=1인 form POST 정확한 원본 본문 폼을 파싱한 뒤 다시 구성
json=1인 JSON POST 정확한 원본 본문 파싱한 JSON을 다시 직렬화

json=1은 post=1보다 우선합니다. 이 옵션들은 티커와 콜백 쌍의 첫 create 호출에서 고정됩니다. 다른 옵션으로 create를 반복해도 기존 주문 설정은 바뀌지 않습니다. 결제 주소를 생성하기 전에 전송 방식을 선택하세요.

프록시 뒤에서 GET을 처리할 때는 신뢰할 수 있도록 설정한 외부 origin에 원래 인코딩된 요청 대상을 결합하세요. 호출자가 제공한 Host나 forwarded-host 헤더로 origin을 정하면 안 됩니다. POST는 JSON이나 폼 미들웨어가 변환하기 전에 원본 본문을 확보하세요. 프레임워크별 입력값 출처는 서명 검증 문서를 참고하세요.

간단한 Node.js 검증기

이 함수는 docs/site/examples/js/verify.js의 JavaScript 예제입니다. 완전한 HTTP 핸들러가 아닌 검증 함수입니다. 공개 키는 별도로 로드하고 검증하세요. 원본 요청 대상과 수정하지 않은 POST 본문이 담긴 Buffer를 전달합니다.

const crypto = require('crypto');

function verifyCallback({ method, requestUri, rawBody, signature }, publicKeyPem, trustedOrigin) {
  let signed;
  if (method === 'GET') {
    signed = Buffer.from(trustedOrigin + requestUri, 'utf8');
  } else if (method === 'POST') {
    if (!Buffer.isBuffer(rawBody) || rawBody.length > 65536) return false;
    signed = rawBody;
  } else {
    return false;
  }
  if (!signature || !/^[A-Za-z0-9+/]+={0,2}$/.test(signature)) return false;
  const verifier = crypto.createVerify('RSA-SHA256');
  verifier.update(signed);
  return verifier.verify(publicKeyPem, signature, 'base64');
}

module.exports = { verifyCallback };

Express에서는 requestUri에 req.originalUrl을 사용하고 파싱 전에 express.raw로 POST 입력을 확보하세요. HTTP 요청을 받는 단계에서도 크기 제한을 적용하세요. 잘못된 키와 검증 예외는 그 단계에서 처리하고 검증 실패로 취급합니다. 검증에 실패하면 HTTP 401을 반환하고 주문은 변경하지 않아야 합니다.

다른 언어와 프록시 처리에 대한 자세한 내용은 RSA-SHA256 콜백 서명 검증을 참고하세요.

검증에는 원본 GET 요청 대상 또는 원본 POST 본문을 사용합니다. Suawave가 보내지 않는 타임스탬프를 서명 메시지에 추가하지 마세요.

2. 검증된 결제를 주문과 연결하기

검증을 마친 뒤 요청을 파싱하고 저장된 주문을 찾으세요. nonce와 주문 참조값을 대조하고 address_in과 coin도 확인합니다. trc20/usdt 주문은 콜백의 coin 필드에서 trc20_usdt를 기대합니다. 금액이나 고객이 입력한 이름으로 티커를 추측하지 마세요.

POST는 본문에 서명하지만 사용자 지정 콜백 쿼리 파라미터는 URL에 남습니다. 서명이 있다고 해서 쿼리의 임의 주문 참조값까지 신뢰할 수 있는 것은 아닙니다. 검증된 입금 주소와 coin을 저장된 주문과 대조하면 정상 본문이 무관한 주문에 연결되는 것을 막을 수 있습니다.

주문마다 콜백 URL에 새롭고 추측할 수 없는 nonce를 생성하고 최초 URL 전체를 서버에 보관하세요. 이 URL은 공개 로그 조회 권한 역할도 하므로 분석 도구와 고객에게 보이는 링크에서 제외하세요. nonce는 주문을 연결하는 데 도움이 되지만 캡처된 서명 이벤트가 최신 요청임을 보장하지는 않습니다.

금액을 반영하기 전에 pending을 확인하세요. 정상 pending 이벤트도 주문 이행의 근거가 될 수 없습니다. 확정 이벤트 역시 금액 확인이 필요합니다. 총입금액, 순수령액, 개별 입금 처리는 암호화폐 부족 입금 가이드를 참고하세요.

3. 영속적인 멱등성으로 재전송 공격 막기

Suawave 공개 콜백에는 타임스탬프와 키 ID가 없습니다. 게이트웨이가 보내지 않는 헤더를 기준으로 5분 유효 시간 검사를 만들어 넣지 마세요. 캡처된 요청은 암호학적으로 계속 유효할 수 있습니다. 같은 요청을 다시 처리해도 추가 효과가 생기지 않도록 하는 것이 방어 수단입니다.

처리한 이벤트 UUID를 결제 기록 및 주문 상태 전이와 같은 데이터베이스 트랜잭션에 영구 저장하세요. UUID에 고유성 제약을 걸어야 합니다. 제약 없이 먼저 “존재하는가?”만 조회하면 두 요청이 동시에 도착할 때 경쟁 상태가 발생할 수 있습니다.

트랜잭션은 다음 순서로 구성할 수 있습니다.

  1. 검증된 이벤트 UUID를 삽입하고, 고유성 충돌은 이미 수락한 이벤트로 처리합니다.
  2. 해당 주문을 잠그고, 확정 이벤트라면 입금의 확정 금액을 기록합니다.
  3. 주문 상태는 앞으로만 전이시키고 필요한 이행 작업을 영구 저장합니다.
  4. 수신 확인을 보내기 전에 커밋합니다.

트랜잭션이 실패하면 성공 수신 확인을 보내지 마세요. 재시도에서 작업을 다시 수행할 수 있습니다. 커밋은 성공했지만 응답 도착 전에 연결이 끊겼다면 재시도는 저장된 UUID를 찾아 주문 변경 없이 수신 확인만 반환합니다.

UUID 중복 제거만으로 중복 배송을 막을 수 있나요?

한 이벤트를 두 번 적용하는 것은 막습니다. 그러나 실제 결제 두 건은 서로 다른 이벤트이므로 주문 단위의 이행 방지 장치도 필요합니다. 주문당 배송 또는 이용 권한 부여 작업을 하나만 영구 생성하고 데이터베이스 고유 키로 제한하세요. 작업을 실행하는 워커도 외부 시스템과 통신할 때 같은 원칙을 유지해야 합니다.

같은 입금의 pending 콜백과 확정 콜백은 UUID가 다릅니다. 이벤트 기록과 함께 입금 단위 상태도 유지하고, 늦게 온 pending 이벤트가 확정을 취소하지 못하게 하세요. 두 콜백이 무엇을 의미하는지는 암호화폐 결제 최종성에서 설명합니다.

같은 UUID로 반복 전달된 요청은 하나의 저장된 주문 작업으로 귀결되어야 합니다. HTTP 200 수신 확인은 해당 작업의 커밋 이후에 반환하세요.

4. 정확히 수신 확인하고 재시도에 대비하기

Suawave는 30초 안에 HTTP 200과 일반 텍스트 본문 *ok*를 기대합니다. 별표 없는 ok도 대소문자 구분 없이 허용합니다. 프레임워크 기본 응답 때문에 수락한 이벤트가 재시도되지 않도록 문서에 명시된 *ok* 응답을 일관되게 사용하세요.

HTTP 204, JSON 성공 객체, 리디렉션은 이 수신 확인에 해당하지 않습니다. 리디렉션은 따라가지 않습니다. 애플리케이션이 요구하는 정확한 경로 표기까지 포함해 최종 HTTPS 콜백 경로를 직접 설정하세요.

전달은 총 8회 시도합니다. 최초 전송 뒤 재시도 지연은 30초, 2분, 10분, 30분, 2시간, 6시간, 24시간이며 각 간격에 최대 10%의 지터가 추가됩니다. UUID는 유지됩니다. 이는 순차적인 재시도 지연 간격이며 특정 시각의 정확한 전달을 보장하지는 않습니다.

오래 걸리는 작업은 요청 처리에서 분리하세요. 이벤트와 이행 작업을 영구 기록하면 포장, 이메일 발송, 권한 부여를 별도로 진행하면서 수신 확인을 반환할 수 있습니다. 메모리 큐에만 넣는 것으로는 영속적 수락을 보장할 수 없습니다. 확인을 보낸 뒤 프로세스가 종료되면 작업이 사라질 수 있습니다.

수신 확인, 순서, 재시도는 콜백 가이드에 설명되어 있습니다. 이미 처리한 유효한 이벤트도 정상 성공으로 응답해야 게이트웨이가 재시도를 중단할 수 있습니다.

5. 임의 키를 신뢰하지 않고 키 교체 처리하기

설정된 Suawave 엔드포인트에서 받은 키를 캐시하세요. 검증에 실패하면 거부하기 전에 키를 한 번 갱신하고 다시 검증합니다. 키가 교체되면 과거 이벤트의 재시도에도 새 서명 키를 사용합니다. 중복 제거를 위한 식별자는 여전히 이벤트 UUID입니다.

콜백이 제공한 URL에서 검증 키를 가져오지 마세요. 같은 요청에서 키를 반복 갱신하지도 마세요. 갱신한 키의 타입과 크기를 확인하고, 재검증에도 실패한 요청은 거부합니다. 키 엔드포인트에 접근할 수 없으면 검증되지 않은 데이터를 수락하지 말고 주문을 그대로 둔 채 전달 재시도를 기다리세요.

유효하지 않은 서명과, 유효하지만 커밋하지 못한 이벤트의 운영 기록은 구분하세요. 전자는 서명 대상 바이트 오류나 신뢰할 수 없는 요청을, 후자는 처리 장애를 시사합니다. 어느 경우든 진단 중 비밀값이 포함된 전체 콜백 URL을 로그에 남기지 마세요.

6. 누락 콜백 대조와 실패 경로 확인하기

최초 콜백 URL로 GET /{ticker}/logs/를 호출해 전달 누락을 조사하세요. sent 결과는 정산은 확정되었지만 확정 콜백의 수신 확인을 받지 못했다는 뜻이며 재시도가 소진된 경우도 포함합니다. done은 확정 콜백의 수신 확인까지 받았다는 뜻입니다. 로그는 대조를 위한 보완 수단이며 정상 결제 인정 경로는 검증된 콜백입니다.

배포 전에 같은 정상 서명 이벤트를 핸들러에 두 번 보내 영구 저장된 작업이 하나만 있는지 확인하세요. 서명 대상 바이트 하나를 바꾸면 반드시 거부해야 합니다. 커밋 전 데이터베이스 실패와 커밋 후 수신 확인 유실도 확인하세요. 확정 이벤트를 pending 이벤트보다 먼저 전달해도 주문은 결제 완료 상태를 유지해야 합니다.

마지막으로 서로 다른 두 주문에서 금액과 네트워크 연결을 확인하세요. 한 입금의 유효한 서명으로 다른 주문이 결제되어서는 안 됩니다. USDT 연동 단계별 가이드는 주문 정보를 저장하는 방법을, USDT TRC20과 BEP20 비교는 모든 결제 기록에서 금액과 함께 네트워크를 보관해야 하는 이유를 설명합니다.