"주문 들어왔어?"
"아니."
"지금은?"
"아니."
서버끼리 이 대화를 30초마다 반복하는 방식이 있습니다.
폴링(polling)이라고 부릅니다.
자동화 도구 재피어(Zapier)의 추정은 이렇습니다.
이런 요청의 98.5%가 헛걸음입니다.
"바뀐 거 없다"는 답만 듣고 끊는 겁니다.
웹훅은 이 대화를 통째로 뒤집습니다.
"생기면 네가 연락해."
에그코드도 자체 서비스를 운영하면서 배포 파이프라인을 이 방식으로 걸어두고 있습니다.
방향이 반대인 API입니다
보통의 API 연동은 내가 상대에게 요청을 보내는 구조입니다.
Webhook은 방향이 반대입니다.
내 서버 주소를 상대 서비스에 미리 등록해둡니다.
그 서비스에 사건이 생기면, 상대가 내 주소로 데이터를 보내줍니다.
전화번호를 남겨두는 것과 같습니다.
계속 전화 거는 대신, 일이 생기면 연락을 받습니다.
기술적으로 대단한 물건은 아닙니다.
상대 서버가 나에게 보내는 HTTP 요청 한 건이 전부입니다.
폴링 대신 쓰는 이유 5가지
하나, 헛걸음이 사라집니다.
30초마다 묻던 요청이 사건이 생길 때 1건으로 줄어듭니다.
둘, 지연이 짧아집니다.
폴링은 아무리 빨라도 주기만큼 늦습니다.
5분 주기면 최악의 경우 5분 뒤에 압니다.
셋, 호출 한도를 아낍니다.
대부분의 API는 시간당 호출 수 제한이 걸려 있습니다.
빈손으로 돌아오는 요청에 한도를 태울 이유가 없습니다.
넷, 폴링으로는 못 잡는 사건이 있습니다.
가상계좌 입금이 대표적입니다.
구매자가 언제 돈을 넣을지는 아무도 모릅니다.
다섯, 코드가 단순해집니다.
주기 실행기와 "어디까지 확인했는지" 기록을 관리할 필요가 없습니다.
지금 실제로 쓰이는 곳
| 서비스 | 사건 → 결과 | 늦게 답하면 |
|---|---|---|
| 깃허브 | 코드 push → 빌드·배포 시작 | 10초 초과 시 실패 처리, 자동 재전송 없음 |
| 토스페이먼츠 | 가상계좌 입금 → 결제 완료 처리 | 10초 안에 2xx 없으면 최대 7회 재전송 |
| 슬랙 | 서버 에러·결제 발생 → 채팅방 알림 | 보내는 쪽으로 쓰는 사례 |
| n8n | 주소로 데이터 수신 → 워크플로 실행 | 주소 유출 시 남이 실행 가능 |
깃허브 — 코드를 올리면 배포가 시작됩니다.
받는 쪽이 10초 안에 응답하지 못하면 실패 처리됩니다.
자동 재전송은 없고, 화면에서 직접 다시 보내야 합니다.
토스페이먼츠 — 가상계좌에 돈이 들어온 순간을 알려줍니다.
10초 안에 2xx 응답이 없으면 최대 7회까지 다시 보냅니다.
슬랙 — 서버 에러나 결제 알림이 채팅방에 꽂힙니다.
n8n — 노코드 자동화의 시작 버튼 역할을 합니다.
주소 하나에 데이터가 들어오면 워크플로가 통째로 돌아갑니다.
이렇게도 붙일 수 있습니다
-
재고가 임계치 아래로 떨어지면 알림 — 공급사 시스템과 연동돼 있으면 발주까지
-
전자계약 서명이 끝나면 프로젝트 폴더와 채널 자동 생성
-
문의 폼이 제출되면 담당자 배정 후 카카오톡 알림
-
긴 AI 작업이 끝나면 결과 회수 — 오픈AI·앤트로픽도 이 방식을 씁니다
붙이기 전에 알아둘 3가지
같은 사건이 두 번 올 수 있습니다.
재전송 때문입니다. 두 번 처리해도 결과가 같도록 막아둬야 합니다.
주소만 알면 아무나 보낼 수 있습니다.
보낸 쪽이 진짜인지 서명으로 확인해야 합니다.
무거운 작업은 나중에 합니다.
일단 응답부터 주고, 처리는 뒤에서 돌립니다.
이 규칙들을 묶은 Standard Webhooks 표준이 있습니다. 오픈AI·트윌리오·수파베이스 등이 채택했습니다.
마치며
웹훅이 늘 정답은 아닙니다.
상대가 제공하지 않으면 폴링이 유일한 방법입니다.
놓치면 안 되는 사건이라면 웹훅과 조회를 함께 쓰기도 합니다.
다만 "실시간으로 붙이고 싶다"는 요구는 많습니다.
그 상당수가 이 한 줄짜리 요청으로 해결됩니다.
연동을 검토하실 때 "웹훅 제공하나요?"를 먼저 물어보십시오.
이 질문 하나로 개발 범위가 크게 줄어드는 경우가 많습니다.
함께 읽어보세요 — SSE로 AI 답변을 한 글자씩 흘려보내는 원리 · 웹소켓을 언제 쓰고 언제 피해야 하는지 · 정기결제 시스템 구축, 외주 의뢰 전 챙길 4가지 · 에그코드 외주 개발 서비스