일이 생기면 알려주는 연결
결제가 끝나거나 예약이 취소되는 그 순간, 상대 회사 서버가 우리 쪽으로 먼저 신호를 보내주는 연결이에요. 우리가 계속 물어보는 대신, 일이 생긴 쪽이 벨을 눌러요. 그 벨을 정확히 받는 일이 우리 몫이 되고요.
쉽게 말하면
가게 뒷문으로 물건이 들어오는 상황을 떠올려 보세요. 방법이 두 가지예요. 하나는 사장님이 5분마다 뒷문을 열어보는 것. 하루 종일 열어봐도 대부분 헛걸음이고, 정작 바쁠 때 놓쳐요. 다른 하나는 배송 온 사람이 도착해서 벨을 누르는 것. 벨이 울릴 때만 나가면 돼요. 웹훅이 이 벨이에요. 결제사·택배사·예약 서비스가 "방금 일이 끝났습니다" 하고 우리 쪽 벨을 눌러줘요.
방향이 핵심이에요. API가 내가 궁금할 때 내가 거는 전화라면, 웹훅은 일이 생겼을 때 상대가 나에게 걸어주는 전화예요. 그래서 웹훅 이야기에는 늘 두 가지가 같이 나와요. 걸려 올 전화를 받을 우리 쪽 주소 하나, 그리고 받은 다음에 할 일이요.
묻는 횟수만큼 서버 부담과 요금이 생겨요. 그런데도 최대 1분 늦게 알아요. 손님은 이미 결제창을 닫았고요.
필요한 순간에 한 번만 오니 빠르고 낭비가 없어요. 대신 **신호를 놓치거나 두 번 받는 상황**을 우리가 다뤄야 해요.
어디에 쓰이나: 우리 가게로 오는 신호들
웹훅은 결제 전용이 아니에요. 우리가 시작하지 않았는데 우리 장부를 바꿔야 하는 일이면 전부 웹훅 후보예요. 실제 서비스에서 자주 오는 신호는 이런 것들이에요.
| 오는 신호 | 무슨 뜻인가 | 못 받으면 벌어지는 일 |
|---|---|---|
| 결제 완료 | 손님 카드 승인이 정상으로 끝났다 | 돈은 들어왔는데 주문서가 안 생겨요. 손님은 결제됐다고 알고 기다려요 |
| 결제 실패·중단 | 승인이 거절됐거나 손님이 창을 닫았다 | 안 팔린 것을 팔린 것으로 잡고 재고부터 빼놔요 |
| 가상계좌 입금 | 무통장 입금이 방금 들어왔다 | 손님은 입금했는데 며칠째 미결제로 남아요. 항의가 가장 많은 사고예요 |
| 정기결제 갱신·실패 | 구독 다음 회차가 통과됐다, 또는 카드가 막혔다 | 돈 안 낸 사람이 계속 쓰거나, 낸 사람이 갑자기 끊겨요 |
| 환불 완료 | 취소 처리가 상대 쪽에서 끝났다 | 환불했는데 우리 화면은 배송 준비 중으로 남아요 |
| 배송 상태 변경 | 택배가 집화·배달 완료로 바뀌었다 | "어디까지 왔어요" 문의를 사람이 매번 찾아 답해요 |
| 예약 취소·변경 | 손님이 예약 서비스에서 시간을 바꿨다 | 취소된 자리를 비워두고, 온 손님과 자리가 겹쳐요 |
오른쪽 칸의 공통점이 보이실 거예요. 신호를 못 받으면 돈과 물건과 자리가 어긋나요. 그래서 웹훅은 있으면 좋은 편의 기능이 아니라 결제 연동과 주문 상태 관리의 필수 부품이에요.
신호 하나가 도착해서 처리되기까지
- 1손님이 결제창에서 결제를 끝내요. 이때 손님 화면은 우리 서비스로 돌아오지만, 그 화면만 믿으면 안 돼요. 손님이 도중에 창을 닫거나 인터넷이 끊길 수 있거든요.
- 2결제사 서버가 우리가 등록해 둔 받는 주소로 신호를 보내요. 손님 화면과 무관하게 서버끼리 오가는 연락이라, 손님이 창을 닫아도 도착해요.
- 3우리 쪽에서 신호를 받아 정말 그 회사가 보낸 것인지 서명을 확인해요. 방법은 아래 세 가지 약속에서 설명해요.
- 4신호에 적힌 주문번호로 우리 장부를 찾아 금액을 대조해요. 맞으면 주문 상태를 결제 완료로 바꿔요.
- 5결제사에 "잘 받았다"는 뜻으로 성공 응답을 짧게 돌려줘요. 이 응답이 없으면 상대는 전달 실패로 봐요.
- 6실패로 보면 결제사가 같은 신호를 다시 보내요. 그래서 같은 신호가 두 번, 세 번 올 수 있어요. 이건 고장이 아니라 원래 그런 구조예요.
응답은 짧게, 무거운 일은 뒤로
신호를 받은 그 자리에서 문자 발송, 영수증 만들기, 재고 계산까지 다 하려 들면 응답이 늦어져요. 상대는 기다리다 실패로 판정하고 다시 보내고, 그게 중복 처리의 씨앗이 돼요. 상태만 먼저 바꾸고 성공 응답을 준 뒤, 알림 발송 같은 일은 그다음에 처리하는 게 정석이에요. 손님이 오면 일단 주문부터 받아 적고, 조리는 그다음에 하는 것과 같아요.
받는 쪽의 세 가지 약속
웹훅 주소는 인터넷에 열려 있는 창구예요. 결제사만 두드릴 수 있는 게 아니라 누구든 두드릴 수 있어요. 그래서 받는 쪽이 지켜야 할 약속이 세 가지 있어요. 개발자나 AI에게 맡기더라도, 사장님이 이 세 가지가 지켜지는지는 물어볼 수 있어야 해요.
| 지킬 것 | 왜 필요한가 | 안 지키면 |
|---|---|---|
| 보낸 사람 확인 | 신호마다 붙어 오는 서명(비밀값으로 만든 표식)을 맞춰 봐요. 진짜 결제사만 만들 수 있는 표식이에요 | 아무나 "결제 완료" 신호를 가짜로 만들어 보내요. 돈 안 내고 주문이 통과돼요 |
| 금액·주문번호 대조 | 신호에 적힌 금액을 우리 장부와 비교하고, 돈이 걸린 건은 결제사에 다시 조회해서 확인해요 | 1,000원 결제로 10만 원 상품이 나가요. 신호 내용만 믿은 대가예요 |
| 두 번 와도 한 번만 처리 | 이미 처리한 주문번호면 아무 일도 하지 않고 성공 응답만 주고 끝내요 | 재고가 두 번 빠지고, 손님에게 문자가 두 번 가고, 환불이 두 번 나가요 |
세 번째 약속은 장부에 도장을 찍는 것과 같아요. 신호를 처리할 때마다 주문번호 옆에 도장을 찍어 두고, 같은 번호가 또 들어오면 도장부터 봐요. 이미 찍혀 있으면 그냥 넘겨요. 도장을 안 보면 같은 주문을 두 번 포장해서 두 번 보내게 돼요.
서명 확인에 쓰는 비밀값은 코드에 적지 않고 환경변수 금고에 둬요. 그리고 신호가 두 번 오는 건 결제사의 잘못이 아니에요. 우리 응답이 늦거나 끊기면 상대는 안 갔다고 보고 다시 보내는 게 맞는 행동이에요. "같은 일이 두 번 들어와도 결과는 한 번과 같게" 만드는 것이 받는 쪽 책임이에요.
심화: 신호는 늦게, 거꾸로, 두 번 와요
규모가 커지면 만나는 진실이 하나 있어요. 웹훅은 순서를 약속하지 않아요. 결제 완료 신호가 재시도로 늦게 오는 사이에 손님이 바로 취소해서, 취소 신호가 먼저 도착할 수 있어요. 늦게 온 결제 완료를 그대로 반영하면 취소된 주문이 다시 살아나요. 그래서 신호에 적힌 시각을 보고, 더 최신 상태만 반영하도록 만들어야 해요.
그리고 신호는 사라질 수도 있어요. 우리 서버가 배포 중이거나 장애로 몇 시간 멈춰 있으면, 상대의 재시도가 다 끝난 신호는 영영 안 와요. 재시도 횟수와 간격은 회사마다 달라서 그쪽 개발 문서가 유일한 근거예요. 그래서 실무의 정답은 벨 하나에 다 걸지 않는 거예요.
벨과 마감 장부, 두 겹으로
평소에는 웹훅(벨)으로 그 순간 처리하고, 하루 한 번은 결제사 거래 목록을 통째로 받아와 우리 장부와 맞춰 봐요. 가게로 치면 벨소리로 일하고 마감 때 장부를 맞추는 거예요. 이 두 겹이 있으면 놓친 신호가 손님 항의 전에 잡혀요. 정산 금액이 어긋나는 사고의 상당수가 이 마감 점검 하나로 예방돼요.
증상이 보이면, AI에게 이렇게 말하세요
웹훅 문제는 증상이 먼저 보여요. 원인을 몰라도 괜찮아요. 아래 표에서 증상을 찾아 오른쪽 문장을 그대로 AI에게 말하면, 어디를 봐야 하는지부터 짚어줘요.
| 증상 | AI에게 말할 문장 |
|---|---|
| 결제는 됐는데 주문이 안 생겨요 | "결제 완료 웹훅이 수신되고 있는지 확인해줘. 수신 기록을 보여주고, 못 받고 있다면 원인을 찾아 고쳐줘." |
| 확인 문자가 두 번 가요 | "웹훅 중복 수신을 막아줘. 이미 처리한 주문번호가 또 오면 아무것도 하지 않고 성공 응답만 주게 해줘." |
| 무통장 입금이 반영이 안 돼요 | "가상계좌 입금 통보 웹훅이 등록돼 있는지, 받은 뒤 주문이 결제 완료로 바뀌는지 점검해줘." |
| 환불했는데 화면은 그대로예요 | "환불 완료 웹훅을 받으면 주문 상태를 환불로 바꾸게 만들어줘." |
| 주소를 옮긴 뒤부터 신호가 안 와요 | "새 도메인 기준으로 웹훅 받는 주소를 알려줘. 결제사 관리 화면에 다시 등록할게." |
| 가끔씩만 누락돼요 | "웹훅 응답이 느려지는 지점을 찾아 무거운 작업을 응답 뒤로 미뤄줘. 하루 한 번 결제 목록과 장부를 맞추는 점검도 넣어줘." |
| 취소가 결제보다 먼저 처리돼요 | "웹훅이 순서 없이 도착해도 안전하게, 신호의 발생 시각을 비교해서 더 최신 상태만 반영하게 해줘." |
공통 요령이 하나 있어요. "고쳐줘" 앞에 "확인해줘"를 먼저 시키는 것. 웹훅 사고는 원인이 우리 쪽(수신 실패)일 수도, 상대 쪽(발송 실패)일 수도 있어서, 수신 기록부터 보는 게 가장 빨라요. 상대가 보냈는지는 결제사 관리자 화면의 전송 기록에서 확인할 수 있어요.
지금은 신경 쓰지 않아도 되는 때
웹훅은 필요해지는 순간이 분명한 기술이에요. 그 순간이 오기 전에는 몰라도 아무 일도 안 생겨요. 겁먹고 미리 공부할 필요 없다는 뜻이에요.
- 1소개 페이지·포트폴리오·예약 문의 폼만 있는 단계. 밖에서 들어와 우리 장부를 바꿀 일이 없으니 웹훅 자체가 등장하지 않아요.
- 2결제·구독·배송·외부 예약 서비스를 아직 안 붙였을 때. 웹훅은 이런 걸 연결하는 순간 같이 따라오는 부품이에요. 연결 전에는 준비할 것도 없어요.
- 3하루 몇 건이고 몇 분 늦어도 되는 일. 예를 들어 통계 갱신처럼 급하지 않은 일은 주기적으로 조회하는 방식으로 충분해요. 웹훅이 항상 정답인 건 아니에요.
- 4상대 서비스가 웹훅을 아예 안 주는 경우. 없는 벨을 만들 수는 없어요. 이때는 조회 주기를 정해두고 시간 초과와 재시도 규칙만 갖추면 돼요.
반대로 결제를 붙이는 날이 웹훅을 신경 쓰기 시작하는 날이에요. 그날이 오면 이 문서의 세 가지 약속과 증상 표만 있으면 돼요. 그 전까지는 이 문서를 닫아두셔도 손해가 없어요.
사장님이 실제로 겪는 장면
장면 1 · 결제사 기술지원 담당자가 말했다
“웹훅 주소 등록해 주시고, 받으시면 200으로 응답 주셔야 해요. 응답이 없으면 재시도가 들어갑니다.”
이제 해석돼요. 받을 주소를 등록하고, 잘 받았다는 표시를 짧게 돌려주라는 뜻이에요. 200은 "정상 처리"를 나타내는 웹의 표준 번호예요. 응답을 안 주면 상대는 못 갔다고 보고 같은 신호를 또 보내요. 재시도는 상대의 친절이고, 두 번 와도 한 번만 처리하는 건 우리 일이에요.
장면 2 · 무통장 입금 손님의 항의 전화
“어젯밤에 입금했는데 아직도 미결제라고 떠요. 주문이 취소된 건가요?”
입금 통보를 못 받았거나, 받고도 처리에 실패한 경우예요. 확인 순서는 정해져 있어요. 결제사 관리자 화면에서 입금 기록과 웹훅 전송 기록을 보고, 보냈는데 실패로 남았으면 우리 쪽 문제예요. 이때는 손님을 기다리게 하지 말고 주문 상태부터 손으로 맞춰 주고, 원인은 그다음에 찾아요. 급한 불부터 끄는 순서는 장애 대응과 같아요.
자주 묻는 것
- Q. 웹훅 주소를 제가 직접 만들어야 하나요?
- 주소를 직접 짓지는 않아요. 결제사나 예약 서비스를 붙이면 우리 쪽에 받는 창구가 하나 생기고, 사장님이 하는 일은 그 주소를 상대 회사 관리 화면에 등록하는 것이에요. 어떤 값이 필요한지는 연결 화면에서 미리 볼 수 있어요.
- Q. 손님 화면이 결제 완료로 바뀌었으면 그걸로 충분하지 않나요?
- 아니에요. 그 화면은 손님 브라우저가 알려주는 것이라 창을 닫거나 인터넷이 끊기면 안 와요. 손님 쪽에서 값을 바꿔 보낼 수도 있고요. 돈이 걸린 판단은 서버끼리 오간 웹훅과 결제사 재조회로 해야 해요.
- Q. 서버가 잠깐 꺼져 있었으면 그 사이 신호는 사라지나요?
- 대부분 몇 번 다시 보내줘요. 다만 횟수와 간격은 회사마다 달라서 그쪽 개발 문서를 봐야 하고, 재시도가 다 끝난 신호는 사라져요. 그래서 웹훅만 믿지 말고 하루 한 번 결제 목록과 장부를 맞추는 점검을 같이 두는 거예요.
- Q. 같은 신호가 두 번 왔어요. 결제사가 잘못한 건가요?
- 아니에요, 정상 동작이에요. 우리 응답이 늦거나 끊기면 상대는 전달 실패로 보고 다시 보내는 게 맞아요. 한 번만 처리되게 만드는 것이 받는 쪽 몫이에요.
- Q. 웹훅 주소가 남에게 알려지면 위험한가요?
- 주소만으로 큰일이 나지는 않지만, 가짜 신호를 보내볼 수는 있어요. 그래서 서명 확인이 필요하고, 확인에 쓰는 비밀값은 코드가 아니라 금고에 둬요. 주소 자체도 굳이 공개하지 않는 게 좋고요.
- Q. 웹훅과 [[api-key|API 키]]는 무슨 관계예요?
- 방향이 반대예요. API 키는 우리가 상대에게 갈 때 내는 출입증이고, 웹훅은 상대가 우리에게 올 때 쓰는 창구예요. 그래서 웹훅에는 상대가 진짜인지 확인하는 표식이 따로 필요해요.
- Q. 결제 완료 신호를 받자마자 손님에게 문자를 보내도 되나요?
- 주문·결제 안내처럼 거래에 필요한 알림은 보낼 수 있어요. 다만 그 문자에 할인·이벤트 같은 광고 내용을 섞으면 정보통신망법에 따라 사전 수신동의가 필요한 광고성 정보가 될 수 있어요. 경계가 애매하면 방송통신위원회와 한국인터넷진흥원의 공식 안내를 확인하고 보내는 게 안전해요.
확인해 보세요
결제 완료 웹훅이 같은 주문번호로 두 번 도착했어요. 올바른 처리는?
하나 더
결제 완료 신호보다 취소 신호가 먼저 도착했어요. 늦게 온 결제 완료는 어떻게 할까요?
직접 해보기
연결 센터에서 받는 창구를 구경해 보세요
결제사·백엔드를 연결하는 곳이에요. 무엇을 붙일 때 어떤 값을 등록하게 되는지 눈으로만 봐도 충분해요. 지금 연결하지 않아도 돼요.
연결 센터 열기더 깊이 (안 읽어도 괜찮아요)
웹훅과 폴링, 실무는 둘 다 씁니다 · 계속 물어보는 방식을 폴링이라고 불러요. 웹훅이 있어도 폴링을 완전히 없애지 않는 이유는 신호를 놓치는 경우가 반드시 생기기 때문이에요. 평소에는 웹훅으로 즉시 처리하고, 하루 한 번은 거래 목록을 통째로 받아 주문 상태와 맞춰 봐요. 이런 맞춰보기를 대사라고 부르는데, 돈이 오가는 서비스라면 규모와 상관없이 두는 게 정석이에요. 참고로 폴링을 너무 촘촘히 돌리면 상대가 요청 제한에 걸어 막기도 해요.
서명 확인이 실제로 하는 일 · 상대 회사는 신호를 보낼 때 내용과 비밀값을 섞어 짧은 표식을 만들어 함께 보내요. 우리도 같은 비밀값으로 표식을 만들어 두 개가 같은지 봐요. 다르면 가짜이거나 내용이 중간에 바뀐 거예요. 주소만 아는 사람은 표식을 만들 수 없다는 점이 핵심이에요. 방식은 회사마다 조금씩 달라 그쪽 개발 문서를 따라야 하고, 비밀값이 새면 자물쇠를 바꾸듯 재발급해요.
받은 신호는 지우지 말고 남겨두기 · 도착한 신호의 원문과 처리 결과를 기록으로 남겨 두면 세 가지가 편해져요. 사고가 났을 때 어디서 틀어졌는지 보이고, 실패한 건을 나중에 다시 처리할 수 있고, 손님과 금액 분쟁이 생겼을 때 근거가 돼요. 다만 신호 안에 손님 연락처 같은 정보가 섞여 있으면 개인정보 규칙에 맞춰 보관 기간을 정해 두세요. 남기는 것과 무한정 쌓아두는 것은 다른 얘기예요.
이것만 기억하세요
- ·웹훅은 일이 생긴 쪽이 우리 벨을 눌러주는 연결이에요. 우리가 계속 묻지 않아도 돼요
- ·돈 판단의 근거는 손님 화면이 아니라 웹훅과 결제사 재조회예요
- ·같은 신호는 두 번 올 수 있고 순서도 뒤집혀요. 한 번만, 최신 상태만 반영해요
- ·받으면 상태만 바꾸고 짧게 응답해요. 문자·영수증은 그다음이에요
- ·결제를 붙이기 전까지는 신경 쓰지 않아도 돼요. 붙이는 날이 시작일이에요