웹훅

실시간 이벤트 알림을 수신하는 웹훅을 설정합니다.

ONDA Platform Engineering 관리

웹훅

웹훅을 사용하여 예약 상태 변경 이벤트를 실시간으로 수신할 수 있습니다.

웹훅 개요

웹훅은 특정 이벤트가 발생했을 때 ONDA가 귀사의 서버로 HTTP POST 요청을 보내는 방식입니다. 주기적으로 API를 호출하여 변경사항을 확인하는 대신, 이벤트 발생 즉시 알림을 받을 수 있습니다.

웹훅 vs 폴링

방식	장점	단점
웹훅	실시간, API 호출 절감, 효율적	서버 엔드포인트 필요
폴링	구현 간단	API 호출 증가, 지연 발생

권장: 실시간성이 중요한 예약 업데이트는 웹훅, 참고용 통계는 폴링

이벤트 타입

이벤트	설명	발생 시점
`reservation.created`	예약 생성됨	예약 API 호출 성공 후 Hub 확정 시
`reservation.cancelled`	예약 취소됨	취소 API 호출 성공 시
`reservation.modified`	예약 변경됨	투숙객 정보 수정 API 호출 성공 시
`reservation.no_show`	노쇼 처리됨	고객 미체크인으로 노쇼 확정 시

웹훅 설정 프로세스

엔드포인트 구현

귀사 서버에 웹훅을 수신할 HTTPS 엔드포인트를 구현합니다.

웹훅 등록

ONDA 개발자 포털에서 웹훅 URL과 수신할 이벤트 타입을 등록합니다.

서명 검증

수신한 웹훅이 ONDA에서 발송한 것인지 서명(HMAC SHA256)을 검증합니다.

이벤트 처리

이벤트 타입에 따라 비즈니스 로직을 실행합니다.

서명 검증

웹훅 요청이 실제로 ONDA에서 발송된 것인지 확인하려면 서명을 검증해야 합니다.

요청 헤더

헤더	설명
`X-ONDA-Signature`	`sha256=<hex>` 형식의 HMAC-SHA256 서명
`X-ONDA-Timestamp`	Unix timestamp (초 단위)

서명 생성 방식

서명 대상 문자열(signing string): ${X-ONDA-Timestamp}.${요청 본문 JSON}

signing_string = timestamp + "." + raw_body
signature = HMAC-SHA256(webhook_secret, signing_string)
header = "sha256=" + hex(signature)

검증 예시 (Python)

import hmac
import hashlib

def verify_webhook_signature(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    signing_string = f"{timestamp}.{raw_body.decode('utf-8')}"
    expected = hmac.new(
        secret.encode('utf-8'),
        signing_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    received = signature.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

# 사용 예시
signature = request.headers.get("X-ONDA-Signature")
timestamp = request.headers.get("X-ONDA-Timestamp")
if not verify_webhook_signature(request.data, signature, timestamp, WEBHOOK_SECRET):
    return {"error": "Invalid signature"}, 401

보안 필수: 모든 웹훅 요청의 서명을 검증하세요. 검증하지 않으면 악의적인 요청에 노출될 수 있습니다.

웹훅 이벤트 구조

모든 웹훅 이벤트는 다음 구조를 따릅니다:

{
  "event_id": "evt_abc123",
  "event_type": "reservation.created",
  "timestamp": "2026-02-08T10:30:00.000Z",
  "data": {
    "booking_id": "...",
    "hub_booking_number": "...",
    "status": "confirmed",
    "property_id": "...",
    "checkin": "2026-03-01",
    "checkout": "2026-03-03",
    "total_amount": "150000",
    "currency": "KRW"
  }
}

공통 필드:

event_id: 이벤트 고유 ID (중복 처리 방지용)
event_type: 이벤트 타입
timestamp: 발생 시각 (ISO 8601)
data: 이벤트별 페이로드

재시도 정책

웹훅 전송이 실패하면 ONDA는 자동으로 재시도합니다.

재시도 스케줄

시도	대기 시간	누적 시간
1차	즉시	0분
2차	5분 후	5분
3차	15분 후	20분
4차	1시간 후	1시간 20분
5차	3시간 후	4시간 20분
6차	6시간 후	10시간 20분

성공 조건

다음 조건을 모두 만족하면 성공으로 간주합니다:

HTTP 상태 코드: 200-299
응답 시간: 10초 이내

실패한 이벤트는 웹훅 전송 로그 API를 통해 조회하고 수동으로 재전송할 수 있습니다.

멱등성 처리

네트워크 문제로 동일한 이벤트가 여러 번 전송될 수 있습니다. 멱등성을 보장하세요.

중복 방지 전략

이벤트 ID 저장: 처리한 event_id를 DB에 저장
중복 확인: 새 이벤트 수신 시 ID 존재 여부 확인
건너뛰기: 이미 처리한 이벤트는 무시

권장 구현 패턴

보안 권장사항

HTTPS 필수: 웹훅 URL은 HTTPS만 허용됩니다
서명 검증: 모든 요청의 서명을 검증하세요
Secret 보호: 웹훅 secret을 환경변수에 안전하게 저장하세요
타임아웃: 10초 이내에 응답하세요 (내부 처리는 비동기로)

무거운 처리는 큐(Queue)에 넣고 비동기로 처리하세요. 웹훅 응답은 10초 이내에 반환해야 합니다.

웹훅

웹훅

웹훅 개요

웹훅 vs 폴링

이벤트 타입

웹훅 설정 프로세스

엔드포인트 구현

웹훅 등록

서명 검증

이벤트 처리

서명 검증

요청 헤더

서명 생성 방식

검증 예시 (Python)

웹훅 이벤트 구조

재시도 정책

재시도 스케줄

성공 조건

멱등성 처리

중복 방지 전략

권장 구현 패턴

보안 권장사항

활용 사례

예약 알림

다음 단계