METAVERSE TIMES: 웹훅(Webhook)이란?

**웹훅(Webhook)**은 서버 간의 비동기적인 실시간 통신 방식으로, 특정 이벤트가 발생했을 때 **자동으로 지정된 URL(엔드포인트)**로 정보를 전송하는 메커니즘입니다.
쉽게 말해, 웹훅은 서버가 "무슨 일이 생겼을 때 상대방에게 먼저 알려주는 방법"입니다.

1. 웹훅(Webhook)이란?

웹훅은 HTTP 기반의 콜백(callback) 메커니즘으로, **이벤트 기반(event-driven)**으로 동작합니다. 사용자가 어떤 행동을 했을 때, 그에 대한 정보를 다른 시스템에 자동으로 알려주는 것이 핵심입니다.

✅ 수동 요청이 아닌 자동 전송
✅ 실시간 데이터 전달
✅ 요청 주체: 이벤트가 발생한 서버

2. 웹훅의 기본 작동 방식

2.1 개념 흐름

클라이언트가 웹훅 URL을 등록
- 예: https://example.com/webhook
이벤트가 발생
- 예: 사용자가 결제를 완료함
서버가 웹훅 URL로 HTTP POST 요청 전송
- JSON, XML 등의 형식으로 데이터 전달
클라이언트는 요청을 받아 필요한 작업 수행
- 예: DB 저장, 알림 발송 등

2.2 구조 예시 (JSON)

json

POST /webhook HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "event": "payment_success",
  "user_id": "12345",
  "amount": 10000,
  "timestamp": "2025-07-26T01:23:45Z"
}

3. 웹훅과 API의 차이점

항목	API (Polling)	웹훅 (Webhook)
요청 주체	클라이언트가 서버에 요청	서버가 클라이언트에 알림
요청 방식	주기적으로 요청 (예: 5분마다)	이벤트 발생 시 자동 요청
네트워크 비용	높음 (빈번한 요청)	낮음 (필요할 때만 요청)
실시간성	낮음 (딜레이 존재)	높음 (즉시 전달 가능)
설정 난이도	쉬움	웹훅 서버 구축 필요

4. 웹훅 사용 사례

4.1 결제 시스템

**PG사(카카오페이, Toss 등)**에서 결제가 완료되면 웹훅으로 결제 성공 정보를 전송
쇼핑몰은 이를 수신하여 주문 상태를 '결제완료'로 업데이트

4.2 GitHub, GitLab

Push, Pull Request, Merge 등 이벤트 발생 시
등록된 웹훅 URL로 자동 알림 (CI/CD 서버 등에서 활용)

4.3 슬랙(Slack) 알림

시스템 에러나 신규 가입 이벤트를 Slack 채널로 자동 전송

4.4 OpenWebUI + Postman + n8n 연동

특정 프롬프트 실행 시 자동으로 외부 시스템 호출

5. 웹훅 서버 구성 방법

5.1 준비사항

웹서버 (예: Node.js, Python Flask, PHP 등)
고정 URL (도메인/IP, 포트)
SSL 인증서 (HTTPS 사용 권장)

5.2 예제 (Node.js + Express)

javascript

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;
  console.log('웹훅 수신 데이터:', payload);
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('웹훅 서버가 3000번 포트에서 실행 중');
});

6. 웹훅 사용 시 주의사항

6.1 보안

Secret Token 사용 → 웹훅 요청의 진위 검증
IP 화이트리스트 설정
HTTPS 사용

6.2 장애 대비

실패한 요청에 대한 Retry 로직 설정 필요
수신 서버가 다운되어도 데이터 유실 방지하는 큐 시스템 사용 고려

6.3 로깅

웹훅 수신 및 처리 결과를 모두 로그에 남겨야 추후 디버깅 용이

7. 실시간 vs 비실시간: 웹훅은 어디에 적합할까?

유형	적합 여부	이유
주문 상태 알림	✅	고객에게 빠르게 처리 결과 알려야 하므로
주기적인 환율 확인	❌	웹훅보다는 주기적인 API 호출(Polling)이 적합
실시간 보안 알림	✅	위협 탐지 시 즉시 대응 가능해야 함

8. 웹훅 테스트 도구 추천

RequestBin
Webhook.site
Postman Webhook Capture
n8n – 자동화 워크플로우 구축 가능
Ngrok – 로컬 웹훅 테스트용 터널링 툴

9. 마무리 요약

항목	내용
정의	서버 간의 실시간 이벤트 기반 통신 방식
동작 방식	이벤트 발생 시 등록된 URL로 POST 요청 전송
장점	실시간 처리, 낮은 네트워크 부담
단점	수신 서버 필요, 보안 취약 가능성
활용 분야	결제 알림, 슬랙 알림, CI/CD, 챗봇 자동화 등

METAVERSE TIMES

웹훅(Webhook)이란?