웹훅이란?

웹훅은 이벤트가 발생하면 한 시스템이 다른 시스템이 등록해 둔 URL로 페이로드를 POST하는 자동화된 HTTP 콜백입니다. 2007년에 “사용자 정의 HTTP 콜백”으로 만들어진 이 용어는 중요한 역전을 가리킵니다. 자사 시스템이 무언가 바뀌었는지 반복해서 묻는 대신, 상대 시스템이 바뀌는 순간 자사 시스템에 알려 줍니다. 웹의 가장 평범한 부품인 HTTPS URL, POST, JSON 본문, 2xx 확인 응답으로 만든 푸시입니다.

핵심 요약

전달, 처음부터 끝까지

설정      수신자가 https://api.example.com/hooks/payments를 노출하고
          제공업체에 등록하며, 이벤트와 비밀(secret)을 선택

이벤트    제공업체에서 결제 성공

전달      POST /hooks/payments
          webhook-id: evt_8fk2            ← 중복 제거 키
          webhook-timestamp: 1767024900   ← 리플레이 방지(서명에 포함)
          webhook-signature: v1,d2Vio…    ← HMAC-SHA256(secret, id.timestamp.body)
          { "type": "charge.succeeded", "orderId": "o-1187" }

ACK       수신자가 서명 검증 → 수 초 안에 200 → 작업은 비동기로 진행
재시도    2xx가 없으면? 수 시간/수 일 동안 지수 백오프 → 중복은 정상

패턴의 양방향을 코드로 보여 줍니다. 송신자인 데이터 트리거, 수신자인 Cloud Function, 그리고 결과를 지켜보기만 하는 클라이언트입니다:

// JavaScript — Cloud Code (cloud/main.js): both directions of a webhook
// OUTGOING: any data change can notify an external system
Parse.Cloud.afterSave('Order', async (req) => {
  if (req.object.get('status') !== 'paid') return;
  await Parse.Cloud.httpRequest({
    method: 'POST',
    url: 'https://hooks.example.com/orders', // the receiver's registered URL
    headers: { 'Content-Type': 'application/json' },
    body: { event: 'order.paid', id: req.object.id },
  });
});

// INCOMING: a Cloud Function is a ready-made webhook receiver
Parse.Cloud.define('paymentWebhook', async (req) => {
  verifySignature(req.params, process.env.WEBHOOK_SECRET); // HMAC first
  await markOrderPaid(req.params.orderId); // write fast, work async
  return { received: true }; // 2xx before heavy processing
});

// Flutter / Dart — Back4app Flutter SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
final orderQuery = QueryBuilder<ParseObject>(ParseObject('Order'))
  ..whereEqualTo('objectId', orderId);
final sub = await LiveQuery().client.subscribe(orderQuery);
sub.on(LiveQueryEvent.update, (order) {
  if (order.get<String>('status') == 'paid') showReceipt();
});
// The webhook itself was handled server-side — clients just watch the data.

// iOS / Swift — Back4app Swift SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
let orderQuery = Order.query("objectId" == orderId)
let sub = try await orderQuery.subscribe()
sub.handleEvent { _, event in
    if case .updated(let order) = event, order.status == "paid" {
        showReceipt()
    }
}
// The webhook itself was handled server-side — clients just watch the data.

// Android / Kotlin — Back4app Android SDK
// The client's side of a webhook: watch its effect in real time
// (payment platform → Cloud Function receiver → database → Live Query → UI)
val orderQuery = ParseQuery.getQuery<ParseObject>("Order")
orderQuery.whereEqualTo("objectId", orderId)
val sub = ParseLiveQueryClient.Factory.getClient().subscribe(orderQuery)
sub.handleEvent(SubscriptionHandling.Event.UPDATE) { _, order ->
    if (order.getString("status") == "paid") showReceipt()
}
// The webhook itself was handled server-side — clients just watch the data.

웹훅 vs. API vs. 폴링

이 논쟁은 대체로 무의미합니다. 성숙한 연동은 셋을 모두 씁니다. 변경을 빠르게 듣는 데는 웹훅, 신뢰할 수 있는 최신 상태를 가져와 행동하는 데는 API 호출, 그리고 공중그네 아래의 안전망으로 느린 대조 폴링입니다.

수신자의 체크리스트

모든 제공업체 문서에 흩어져 있지만 어떤 설명 글도 모아 놓지 않은 목록입니다:

1. 원본 본문에 대해 HMAC을 검증합니다 – 파싱 전에 해야 합니다. 다시 직렬화한 JSON은 서명을 깨뜨립니다.
2. 상수 시간으로 비교합니다 – 문자열 동등 비교는 타이밍을 누설합니다. 암호화 라이브러리의 비교 함수를 사용해야 합니다.
3. 타임스탬프 창을 강제합니다 – 약 5분보다 오래된 전달은 거부합니다. 타임스탬프가 서명된 내용 안에 있으므로, 공격자는 유효하게 서명된 오래된 요청을 새 시각으로 리플레이할 수 없습니다.
4. 2xx를 빠르게 반환합니다 – 무거운 작업 전에, 수 초 안에 반환합니다. 느린 핸들러는 타임아웃되고 재시도되어 중복 폭풍이 됩니다.
5. 비동기로 처리합니다 – 큐에 넣고, 확인 응답한 뒤, 작업합니다.
6. 이벤트 ID로 중복을 제거합니다 – 처리한 ID 기록을 제공업체의 재시도 기간 이상 보관합니다.
7. 중요한 동작에서는 페이로드를 신뢰하지 않습니다 – 웹훅을 초인종으로 취급합니다. 상품을 발송하거나 접근을 허가하기 전에 제공업체의 API에서 현재 상태를 가져옵니다.
8. 전달을 로깅하고 실패에 경보를 겁니다 – 침묵은 망가진 엔드포인트와 구별되지 않습니다.

정의 페이지들이 건너뛰는 로컬 개발 메모 하나입니다. localhost는 인터넷에서 접근할 수 없으므로, 개발은 자신의 머신에 공개 URL을 빌려주는 터널링 도구와 실제 페이로드를 리플레이하는 캡처 도구를 거쳐 진행됩니다.

전달 의미론, 솔직하게

웹훅 전달은 최소 한 번(at-least-once)입니다. 제공업체는 확인 응답을 받을 때까지 재시도하므로, 중복은 신뢰성의 버그가 아니라 신뢰성의 기능입니다. 신뢰할 수 없는 네트워크 위에서 정확히 한 번 전달은 형식적으로 불가능하며, 실용적인 등가물은 최소 한 번 전달에 멱등한 핸들러를 더한 것입니다. 순서는 보장되지 않습니다. 재시도와 병렬 전송이 뒤섞이므로 updated가 created보다 먼저 도착할 수 있습니다. 이벤트를 ID와 버전으로 적용하거나 상태를 다시 가져와야 합니다. 그리고 재시도 기간은 끝납니다. 주말 동안 다운된 엔드포인트는 이벤트를 영구히 놓칠 수 있으며, 그래서 돈이 걸린 중요한 연동은 웹훅에 주기적 대조를 짝지어 둡니다. 브로커가 형식화하는 같은 최소 한 번 규율이 평범한 HTTP로 도착하는 것입니다. 이 비교는 일반화됩니다. 웹훅은 알려진 URL로의 지점 간 푸시이고, pub/sub는 브로커, 토픽, 팬아웃을 더하며, 웹소켓과 SSE는 서버가 아닌 클라이언트를 상대합니다. 웹훅은 인프라를 공유하지 않는 두 시스템이 서로의 이벤트를 들어야 할 때를 위한 답입니다.

송신자 측 구축하기

웹훅을 신뢰성 있게 내보내는 것은 그 자체로 작은 시스템이며, 어떤 순위 페이지도 그 윤곽을 그려 주지 않습니다. 죽은 엔드포인트 하나가 나머지를 막지 않도록 목적지별 큐, 지수 백오프와 지터를 더한 재시도, 시도 횟수가 소진된 뒤 재전달 도구를 갖춘 데드 레터 저장소, 엔드포인트별 시크릿과 시크릿 회전을 갖춘 HMAC 서명, 수신자가 원하는 것만 선택하는 이벤트 유형 구독, 그리고 고객이 읽을 수 있는 전달 로그입니다. “보내긴 했습니까?”가 첫 번째 지원 질문이기 때문입니다. 송신자에게만 해당하는 보안 항목이 하나 있습니다. 수신자는 임의의 URL을 등록하므로 내부 주소 범위와 대조해 검증해야 합니다. 공격자가 http://10.0.0.5/admin을 자신의 “웹훅 엔드포인트”로 등록하는 것은 연동 기능의 탈을 쓴 서버 측 요청 위조입니다.

일반적인 사용 사례

• 결제 수명 주기 – 결제, 환불, 구독 변경이 정산되는 대로 백엔드에 통보됩니다.
• CI/CD 트리거 – git push가 빌드를 시작하는 전형적인 연결.
• 앱 간 자동화 – 폼 도구, 채팅 플랫폼, CRM이 서로의 이벤트로 연쇄됩니다.
• 운영 알림 – 모니터링 경보와 배송 업데이트가 팀 채널에 도착합니다.
• 데이터 동기화 – 파트너 시스템의 API 전체를 폴링하지 않고도 로컬 미러를 최신으로 유지합니다.

웹훅을 사용해야 할까? 결정 매트릭스

한계와 트레이드오프

• 재시도 기간 너머의 전달은 최선 노력입니다. 웹훅은 알릴 뿐 보장하지 않습니다. 놓쳐서는 안 되는 것은 대조 폴링이 뒷받침합니다.
• 수신자는 가동 시간의 의무를 물려받습니다. 자사 엔드포인트의 가용성이 이제 다른 누군가의 이벤트를 좌우합니다. 배포, 콜드 스타트, 타임아웃이 모두 연동 버그가 됩니다.
• 보안은 직접 켜야 적용됩니다. 검증하지 않는 웹훅 엔드포인트는 인증 없는 쓰기 API입니다. HMAC 체크리스트가 연동과 주입의 차이입니다.
• 디버깅이 두 회사에 걸칩니다. 양측의 전달 로그와 리플레이 도구가 “도착하지 않았다”를 대치 상태에서 diff로 바꿉니다.
• 페이로드는 변합니다. 제공업체는 이벤트 스키마의 버전을 올리고, 정확한 모양에 고정된 소비자는 조용히 깨집니다. 방어적으로 파싱하고 알 수 없는 필드는 무시해야 합니다.

Back4app에서의 웹훅

Back4app은 관리형 데이터베이스, 자동 생성되는 REST 및 GraphQL API, 인증, 파일 스토리지, Cloud Code 서버리스 함수를 결합한 오픈소스 Backend as a Service(BaaS) 플랫폼입니다. 코드 탭이 보여 주듯, 패턴의 두 절반 모두 Cloud Code 구성 요소 하나면 됩니다. 나가는 방향: 데이터를 지켜보는 afterSave 트리거가 Parse.Cloud.httpRequest로 등록된 어떤 URL이든 호출합니다. 함수를 작성하는 것만으로 앱이 웹훅 제공업체가 되며, 송신자 측 규율(실패 시 재시도, 전달 로깅)도 같은 파일에 담깁니다. 들어오는 방향: HTTPS로 노출된 Cloud Function이 준비된 수신자입니다. 서버 측 설정에 둔 시크릿으로 HMAC을 검증하고, 결과를 데이터베이스에 쓰고, 빠르게 반환하면, 업데이트는 Live Query를 통해 열려 있는 모든 화면으로 팬아웃됩니다. 결제 플랫폼의 이벤트에서 사용자의 영수증까지, 어느 단계에서도 직접 운영할 서버 없이 루프가 완성됩니다.