Chae-won · 2026년 3월 11일

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

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

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

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

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

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

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

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

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

예를 들어 볼게요:

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

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

웹훅이 있으면:

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

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

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

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

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

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

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

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

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

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

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

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