웹훅이란? 비개발자를 위한 쉬운 설명

안녕하세요, 채원이에요.

3Min API를 소개하다 보면 "웹훅이 뭔가요?"라는 질문을 정말 많이 받아요. 개발자 사이에서는 너무 당연한 개념인데, 비개발자 분들에게는 한 번도 들어본 적 없는 단어일 수 있거든요.

오늘은 웹훅이 뭔지, 왜 필요한지, 비유를 통해 최대한 쉽게 설명해 볼게요.

시작 전에 딱 하나만요. 사실 웹훅은 API와 기술적으로 완전히 같은 도구예요. 창구도, 메시지 모양도, 인증 방식도 다 같고, 다른 건 "누가 먼저 부르느냐" 하나뿐이에요. 제가 부르면 API, 상대가 먼저 부르면 웹훅이라고 이름만 달리 부르는 거죠. 그래서 "애초에 API가 뭔지도 모르겠는데요?" 하시는 분은, yeonghyeon님이 쓰신 비개발자 사장님을 위한 API 기초 가이드를 먼저 한 번 훑고 오셔도 좋아요. 이미 API가 감이 잡히시는 분은 바로 다음 택배 비유로 건너뛰셔도 괜찮고요.

택배 알림으로 이해하는 웹훅

택배를 시켰다고 해 볼게요. 두 가지 방법으로 배송 상태를 확인할 수 있어요.

방법 1: 직접 확인하기
택배 앱을 열어서 "지금 어디쯤 왔지?" 하고 새로고침을 계속 눌러요. 아침에 한 번, 점심에 한 번, 퇴근 전에 또 한 번. 바뀐 게 없어도 계속 확인하죠. 이게 IT에서 말하는 폴링(polling)이에요.

방법 2: 알림 받기
택배 앱에서 "배송 상태가 바뀌면 알려줘"라고 설정해 두면, 상태가 바뀔 때만 푸시 알림이 와요. 내가 확인하러 가는 게 아니라, 변화가 생겼을 때 알아서 알려주는 거예요. 이게 바로 웹훅(webhook)이에요.

좀 더 정확히 말하면

웹훅은 "어떤 이벤트가 발생하면, 지정된 URL로 데이터를 보내주는 것"이에요.

예를 들어 볼게요:

• 쇼핑몰에서 주문이 들어오면 → 우리 시스템으로 주문 데이터를 보내준다
• 결제가 완료되면 → 우리 대시보드에 결제 정보가 자동으로 기록된다
• 고객이 설문을 제출하면 → 우리 스프레드시트에 응답이 추가된다

공통점이 보이시나요? "~하면 → ~한다"의 패턴이에요. 내가 가서 가져오는 게 아니라, 상대방이 알아서 보내주는 거예요.

왜 웹훅이 중요한가요?

비즈니스에서 데이터는 빠르게 흘러야 해요. 거래처에서 주문을 넣었는데, 그걸 우리가 3시간 뒤에 수동으로 확인한다면? 그 사이에 놓치는 것들이 생겨요.

웹훅이 있으면:

• 실시간으로 데이터가 도착해요. 주문이 들어오는 순간 알 수 있어요
• 자동이에요. 사람이 확인하러 갈 필요가 없어요
• 효율적이에요. 변화가 있을 때만 데이터가 오니까, 쓸데없는 트래픽이 없어요

3Min API에서의 웹훅

3Min API에서는 웹훅이 이렇게 동작해요.

거래처가 우리 API 엔드포인트로 데이터를 보내면, 3Min API가 그 데이터를 저장하는 동시에 우리가 지정한 URL로 자동 전달해 줘요. 예를 들어 우리 CRM이나, 슬랙 채널이나, 자체 시스템으로요.

설정도 간단해요. 엔드포인트를 만들 때 "이 URL로 보내줘"라고 적어두면 끝이에요. 데이터가 들어올 때마다 알아서 전달돼요.

혹시 웹훅 전달이 실패하면? 3Min API가 자동으로 재시도해요. 최대 3번까지. 그래도 안 되면 기록이 남아서 나중에 확인할 수 있어요.

웹훅 vs 폴링, 뭐가 더 좋은가요?

결론부터 말하면, 대부분의 비즈니스 상황에서는 웹훅이 훨씬 나아요.

폴링은 "혹시 새로운 거 있어?" 하고 계속 물어보는 거예요. 아무것도 없어도 물어봐요. 서버 자원도 쓰고, 응답도 느리고, 비용도 더 들어요.

웹훅은 "새로운 거 생기면 알려줘"예요. 필요할 때만 동작하니까 효율적이에요.

다만, 웹훅을 받으려면 "알림을 받을 주소"가 있어야 해요. 일반적으로는 서버가 필요하다는 뜻인데 — 바로 이 부분에서 3Min API가 도움이 돼요. 서버 없이도 웹훅을 수신할 수 있는 엔드포인트를 만들어주니까요.

웹훅이 안 올 때 확인할 것

웹훅을 설정했는데 데이터가 안 들어온다면, 당황하지 마세요. 대부분 아래 항목 중 하나가 원인이에요.

• URL이 정확한가요? — 오타가 가장 흔한 원인이에요. 특히 https://와 http://를 확인하세요. 대부분의 서비스는 HTTPS만 허용해요
• 인증 정보가 맞나요? — API 키나 인증 헤더가 잘못 설정되어 있으면 403 에러로 거부돼요
• 수신 측에 요청 제한이 있나요? — 일부 시스템은 초당 또는 분당 받을 수 있는 요청 수에 제한이 있어요 (rate limit). 제한을 초과하면 데이터가 거부돼요
• 응답 시간이 너무 느린가요? — 웹훅을 보내는 쪽은 보통 5~10초 안에 응답을 기대해요. 응답이 늦으면 실패로 처리할 수 있어요
• 방화벽이 막고 있나요? — 자체 서버로 웹훅을 받는 경우, 방화벽이나 IP 화이트리스트 설정을 확인하세요

3Min API를 수신 측으로 사용하면 위 대부분의 문제를 신경 쓸 필요가 없어요. HTTPS, 인증, 서버 가용성을 서비스가 알아서 관리하니까요. 하지만 3Min API에서 웹훅을 전달받는 우리 쪽 시스템이 있다면, 위 항목을 꼭 점검해 보세요.

정리하면

• 웹훅은 "이벤트가 생기면 자동으로 알려주는 것"이에요
• 택배 앱의 푸시 알림과 같은 원리예요
• 비즈니스 데이터를 실시간으로, 자동으로, 효율적으로 받을 수 있어요
• 서버가 없어도 3Min API로 웹훅을 받을 수 있어요
• 안 올 때는 URL, 인증, 요청 제한, 응답 시간, 방화벽을 확인하세요

웹훅이라는 단어가 어렵게 느껴졌다면, 이제는 좀 친숙해지셨길 바라요. 결국 "알아서 보내주는 것" — 그게 전부예요.