토스페이먼츠 웹훅 설정부터 재전송 정책까지, 알아야 할 5가지

얼마 전, 제 지인은 온라인 쇼핑몰을 운영하면서 토스페이먼츠 웹훅 설정에 어려움을 겪었습니다. 설정은 잘했지만, 웹훅이 제대로 작동하지 않아 결제 상태를 제때 확인할 수 없었다고 합니다. 이러한 문제는 저도 블로그를 운영하며 여러 번 들어본 적이 있습니다.

웹훅 설정 과정은 생각보다 간단해 보이지만, 세부적인 재전송 정책까지 있는 만큼 낮선 분들에게는 다소 복잡하게 느껴질 수 있습니다. 오늘은 이러한 토스페이먼츠 웹훅 설정과 관련해 알아두어야 할 다섯 가지 중요한 점을 함께 살펴보겠습니다.

1. 웹훅 등록 과정: 개발자센터의 핵심 단계

토스페이먼츠의 웹훅 등록은 개발자센터에서 시작됩니다. 웹훅 메뉴에서 ‘웹훅 등록하기’ 버튼을 클릭해 웹훅의 이름과 URL을 입력하면 처음 걸음입니다. 그런 다음 이벤트들이 무엇을 뜻하는지 이해하고 적절히 선택해야 합니다.

등록할 웹훅은 상점아이디(MID)별로 구분됩니다. 이게 무슨 뜻인지 모른다면, 간단히 이해하세요: 별도의 상점 관리로 데이터를 분리해 관리할 수 있는 것입니다. 이렇게 하면 대규모 데이터를 안전하게 처리할 수 있습니다.

각 MID에 따라 이벤트가 개별 전송됩니다. 이에 따라 설정이 누락되거나 오류가 발생할 가능성을 미리 차단할 수 있습니다. 웹훅을 한 번에 등록해도 각각의 특성을 이해하는 것이 필수적입니다.

2. 웹훅 응답 시간과 실패 시 재전송 규칙

웹훅은 이벤트 발생 시 10초 이내에 HTTP 200 응답이라는 신호를 보내야 합니다. 이 짧은 시간 내에 응답하지 않으면 상태가 ‘성공’으로 전환되지 않습니다. 서버가 이를 인식하지 못하면, 사업 운영에도 직접적 영향을 미칠 수 있습니다.

최초 전송이 실패할 경우 재전송이 시작됩니다. 최대 7회까지 재전송하며, 시간 간격은 최초 전송 후 3일 19시간까지 지정되어 있습니다. 각 회차별 간격은 1, 4, 16, 64, 256, 1024, 4096 분으로 점차 늘어납니다.

이 과정 중 발생하는 전송 실패 정보는 이메일을 통해 전달됩니다. 이 메일은 빠르게 문제를 확인하고 대처할 수 있도록 도와줍니다. 정기적인 이메일 확인은 중요합니다.

3. 실패한 웹훅 재시도와 방화벽 체크

‘전송 중’ 상태에서 ‘다시 시도’ 버튼을 누르면 대기 중인 재전송은 중단되고, 새로운 요청이 시작됩니다. 이는 처음 설정 시 모든 절차가 정상인지 확인하는 중요한 단계입니다. 빠른 대처는 곧 성공적인 운영으로 이어질 수 있습니다.

지속적으로 실패하는 경우에는 웹훅 URL의 포트가 방화벽에서 허용되고 있는지 점검해야 합니다. 이는 외부 설정 문제로 웹훅이 차단될 수 있는 상황을 방지하는 역할을 합니다. 서버 설정이 복잡한 경우 전문가 조언을 받는 것도 방법입니다.

이 문제는 특히 보안이 중요한 결제 시스템에서 간과해서는 안 되겠습니다. 필요시 방화벽 설정을 수정하세요. 서버 관리자는 이러한 부분을 미리 점검해 혜택을 받는 것이 좋습니다.

4. 로컬 서버에서 웹훅을 시뮬레이션하는 법

로컬 서버에서 웹훅을 테스트하고 싶다면 ngrok 같은 도구를 사용해야 합니다. 로컬 포트가 포함된 URL은 직접 등록할 수 없기 때문입니다. ngrok은 터미널에서 ‘ngrok http [포트 번호]’ 명령어로 실행합니다.

이렇게 생성된 URL을 웹훅 등록 페이지에 엔드포인트로 설정하고, 테스트 결제를 진행하면 웹훅을 정상적으로 받을 수 있습니다. ngrok의 인스펙터 기능으로 이벤트 데이터를 바로 확인할 수도 있습니다.

이 과정에서 발생할 수 있는 오류를 미리 방지하기 위해, 웹훅의 전송 기록과 본문을 꼼꼼히 확인하세요. 이를 통해 추가적인 문제를 미리 발견할 수 있습니다.

5. HTTPS 사용의 권장과 안전한 설정 유지

토스페이먼츠는 웹훅 전송 시 HTTP를 지원하지만, HTTPS를 사용하는 것을 적극 권장합니다. HTTPS는 웹사이트와 방문자 간의 데이터를 암호화하여 전송하는 방식으로, 보안이 강화된 프로토콜입니다.

이러한 방식은 민감한 사용자 정보가 많이 다뤄지는 결제 시스템에서는 필수적입니다. 이를 통해 사이버 공격이나 비정상적인 트래픽을 예방할 수 있습니다. 보안은 고객 신뢰와 직결되므로 꼼꼼히 점검해야 합니다.

웹훅 설정이 복잡하더라도, 보안을 우선시하는 자세를 잊지 마세요. 제대로 설정된 웹훅은 고객 만족도에도 큰 차이를 가져올 것입니다.

끝으로, 토스페이먼츠 웹훅 설정과 재전송 정책은 간단한 듯 보이지만 각 이벤트와 응답 시간 등을 정확하게 이해하고 적용하는 것이 중요합니다. 문제 발생 시 빠른 대처와 정확한 설정 유지가 성공적인 결제 관리의 핵심입니다. 실수를 줄이기 위해, 설정 전 확인과 테스트는 필수입니다. 지속적인 모니터링을 통해 안정적인 운영을 보장하세요.