본문으로 건너뛰기

웹훅이란, API 비교표와 설정 점검 5가지

웹훅이 무엇인지 연동 회의에서 바로 쓸 수 있게 정리했습니다. API 호출과 나란히 놓은 비교표, 결제 완료 알림이 오가는 순서와 실제 재전송 간격 예시, 받는 주소 · 서명 확인 · 재전송 · 중복 처리 · 기록 다섯 가지 점검표, 개발 없이 웹훅을 받는 방법을 담았습니다.

웹훅이란, API 비교표와 설정 점검 5가지

웹훅(webhook)은 결제 완료 · 주문 접수 · 폼 제출 같은 일이 생기면 상대 서비스가 우리 쪽 주소로 그 내용을 먼저 보내 주는 방식이고, API 호출은 우리가 필요할 때 상대에게 물어보는 방식입니다. 웹훅은 기다리지 않아도 일이 생긴 직후 알 수 있고, API 호출은 원하는 때 원하는 자료를 가져올 수 있어 연동에서는 둘을 함께 씁니다. 웹훅을 받는 쪽은 받는 주소 · 서명 확인 · 재전송 대응 · 중복 처리 · 기록 다섯 가지를 갖추면 됩니다.

API · 서버 같은 기본 용어는 API·서버·배포 뜻 — 개발 회의 용어에 정리돼 있습니다.

웹훅은 API 호출과 무엇이 다른가요

택배로 치면 API 호출은 배송 조회 화면을 직접 열어 보는 일이고, 웹훅은 도착하면 문자가 오는 일입니다. 같은 자료를 두고 누가 먼저 말을 거느냐가 다릅니다.

구분API 호출웹훅
먼저 움직이는 쪽우리 프로그램이 요청상대 서비스가 전송
알게 되는 때우리가 물어본 때(주기적으로 묻기도 함)일이 생긴 직후
우리가 준비할 것발급받은 키, 요청 코드외부에서 접속되는 받는 주소
맞는 일목록 조회 · 등록 · 수정결제 · 주문 · 배송 상태 변화 알림
놓쳤을 때다시 물으면 됨상대의 재전송을 받거나 조회 API로 맞춤
예오늘 들어온 주문 목록 가져오기결제 완료 알림 받기

일정한 간격으로 계속 묻는 방식은 폴링이라고 합니다. 5분마다 새 주문이 있는지 묻는 식인데, 새 일이 없어도 계속 묻고 그 사이 생긴 일은 다음 차례에야 알게 됩니다. 알림을 보내 주는 서비스라면 상태 변화는 웹훅으로 받고, 상세 자료는 API로 가져오는 조합으로 씁니다.

결제 완료 웹훅은 어떤 순서로 오가나요

  1. 고객이 결제를 마칩니다.
  2. PG(결제대행사)가 결제 상태 변경 이벤트를 우리가 등록한 주소로 보냅니다. 한 PG 문서 기준으로 이벤트는 HTTP POST로 오는 JSON 데이터입니다.
  3. 받는 서버가 서명을 검증하거나 조회 API로 실제 결제인지 확인합니다.
  4. 받았다는 뜻으로 200 응답을 돌려줍니다. 같은 문서는 10초 안에 200 응답을 보내라고 안내합니다.
  5. 이벤트 번호(또는 결제 번호)로 이미 처리한 건인지 보고, 처음이면 주문을 결제 완료로 바꿉니다.
  6. 주문 확정 메일이나 알림톡을 보냅니다.

200 응답을 받지 못하면 보낸 쪽이 다시 보냅니다. 한 PG가 공개한 재전송 간격은 아래와 같고, 처음 전송이 실패하면 최대 7회, 처음 보낸 때부터 3일 19시간에 걸쳐 다시 보냅니다. 공식 안내에서 확인한 내용이며 바뀔 수 있습니다.

재전송 차례직전 시도 뒤 간격처음 보낸 뒤 누적(계산)
1회1분1분
2회4분5분
3회16분21분
4회64분1시간 25분
5회256분5시간 41분
6회1,024분22시간 45분
7회4,096분3일 19시간 1분

재전송이 있다는 것은 같은 알림이 두 번 이상 올 수 있다는 뜻이기도 합니다. 우리 서버가 처리는 했는데 응답이 늦어 실패로 기록되면, 같은 이벤트를 한 번 더 받게 됩니다.

웹훅 설정 때 무엇을 점검하나요

서명 방식 · 재전송 규칙은 서비스마다 다르므로 아래는 일반 원리입니다. 실제 값은 쓰는 서비스의 개발 문서에서 확인합니다.

점검정할 것확인하는 법
1. 받는 주소외부에서 접속되는 HTTPS 주소, 받을 이벤트 종류내 컴퓨터 주소(localhost)는 등록할 수 없어 개발 중에는 외부 접속 도구로 시험
2. 서명 확인보낸 쪽이 비밀 키로 만든 서명을 머리글(헤더)에서 꺼내 검증받은 본문을 고치지 않은 원문 그대로 검증하고, 시각이 너무 오래된 요청은 거절
3. 재전송 대응받자마자 2xx 응답, 무거운 처리는 응답 뒤로처리 시간이 응답 제한 시간을 넘지 않는지 시험
4. 중복 처리이벤트 ID를 저장해 이미 처리한 건은 건너뜀같은 이벤트를 두 번 보내 주문 상태가 한 번만 바뀌는지 시험
5. 기록받은 원문 · 받은 시각 · 응답 코드 · 처리 결과서비스 쪽 전송 기록 화면과 하루 한 번 대조

서명 검증의 한 예로, 해외 결제 서비스 한 곳은 요청 본문 · 서명 머리글 · 서명용 비밀 값으로 검증하게 하고, 본문을 조금이라도 바꾸면 검증이 실패하며, 기본 허용 시차를 5분으로 둡니다. 같은 문서는 이벤트가 생긴 순서대로 전달된다고 약속하지 않으니 처리 여부는 이벤트 ID로 가리라고 안내합니다. 취소 알림이 결제 완료 알림보다 먼저 와도 꼬이지 않도록, 알림을 받으면 그 순간의 상태를 조회 API로 다시 읽어 반영하는 쪽이 안전합니다. 서명을 붙이지 않는 이벤트라면 이 조회 확인이 곧 출처 확인이 됩니다.

개발 없이 웹훅을 받을 수 있나요

  • 노코드 자동화 도구 — 웹훅 받기 트리거를 고르면 받는 주소를 만들어 주고, 받은 값으로 시트에 행 추가 · 메신저 알림 같은 다음 동작을 잇습니다. 한 도구는 이 기능을 Catch Hook이라는 이름으로 둡니다.
  • 구글 앱스 스크립트 웹앱 — doPost 함수로 받아 시트에 쌓습니다. 공식 문서의 요청 정보 표에는 머리글 항목이 없어 머리글로 오는 서명을 검증하기 어렵고, 한 번 실행 6분 같은 한도가 있습니다. 앱스 스크립트 기본은 구글 앱스 스크립트 사용법, 자동화 예시 5개에 있습니다.

폼 제출 알림 · 사내 메신저 알림처럼 돈이 오가지 않는 이벤트는 이런 방법으로 시작할 수 있습니다. 결제 · 환불처럼 서명 확인과 중복 처리가 꼭 필요한 이벤트는 서버에서 받는 업무 시스템으로 만듭니다. 카카오톡 챗봇에 외부 서버(스킬)를 붙여 주문 조회 답을 주는 일도 외부에서 접속되는 우리 쪽 주소를 준비한다는 점에서 비슷합니다 — 카카오톡 챗봇, 자동응답 만드는 6단계와 비용에 순서가 있습니다.

자주 묻는 질문

웹훅과 웹후크는 같은 말인가요?

같은 말입니다. 영어 webhook을 옮긴 표기가 웹훅 · 웹후크 · 웹 훅으로 나뉠 뿐이고 뜻은 같습니다. 개발 문서를 검색할 때는 영어 webhook으로도 찾아봅니다.

웹훅 주소가 알려지면 위험하지 않나요?

받는 주소는 누구나 요청을 보낼 수 있는 창구라고 보고 설계합니다. 서명을 검증하거나, 받은 결제 번호로 조회 API를 불러 실제 상태를 확인한 뒤에만 주문을 바꾸면 가짜 요청이 와도 반영되지 않습니다.

웹훅이 오지 않으면 어디부터 보나요?

서비스 개발자 화면의 전송 기록에서 상태와 응답 코드를 먼저 봅니다. 한 PG 문서는 전송이 계속 실패하면 등록한 주소의 포트가 방화벽에서 허용돼 있는지 확인하라고 안내하고, 실패한 전송을 화면에서 다시 시도하는 기능도 둡니다.

웹훅을 쓰면 API 호출은 필요 없나요?

둘 다 씁니다. 알림은 놓치거나 순서가 바뀌어 올 수 있어, 받은 뒤 조회 API로 상태를 확인하고 하루 한 번 목록 조회로 빠진 건을 맞춥니다.

오늘 할 일

쓰고 있는 결제 · 주문 · 폼 서비스 하나의 개발 문서에서 웹훅 항목을 찾아 이벤트 종류 · 재전송 규칙 · 서명 방식 세 가지를 적어 보세요.

이어서 읽기 — 구글 앱스 스크립트 웹앱, 배포 순서와 권한표

FacebookX

이 글과 맞는 서비스

이어서 읽기

블로그 전체 글 목록 →

카카오톡 상담식스원 고객센터 카카오톡 채널 (새 창)