아웃바운드 웹훅 전송 설정
대부분의 호텔은 5~10분이면 완료할 수 있습니다.
이 가이드는 게스트 검증 및 PMS 동기화 후 JSON guest_verified 이벤트를 전송하는 방법을 안내합니다.
이동 경로: Settings → Outbound Webhook
모든 전송에는 X-Vouch-Signature가 포함됩니다.
수신 측에서는 페이로드를 신뢰하기 전에 이 헤더를 검증해야 합니다.
이 페이지에 액세스할 수 있는 사람은 저장된 헤더 값과 HMAC 서명 비밀값을 볼 수 있습니다. 전송 로그에는 전체 요청 페이로드와 응답 세부 정보가 표시됩니다. 감사 변경 기록에서는 계속 이러한 값을 마스킹합니다. Settings → Outbound Webhook에 대한 액세스를 보호하고 스크린샷을 공유하지 마세요.
빠른 참고
| 설정 | 제어 항목 | 보이는 내용 |
|---|---|---|
| Enabled | 아웃바운드 웹훅 전송을 켜거나 끔 | 저장 후에도 토글이 켜진 상태로 유지됩니다 |
| Webhook URL | 전송 대상 URL | AVA가 수신자 URL을 허용합니다 |
| Headers | 수신 측용 고정 인증 헤더 | 저장된 값이 저장 후에도 계속 표시됩니다 |
| Payload Fields | 전송할 게스트 필드 | 선택한 필드만 전송에 표시됩니다 |
| Marketing consent | 최상위 marketingConsent 포함 여부 | 상태 카드에 Included 또는 Omitted가 표시됩니다 |
| Max attempts | 실패한 전송의 재시도 횟수 | 값은 1~10 사이로 유지됩니다 |
| HMAC signing secret | 각 전송의 페이로드 서명 | 저장된 값이 계속 표시되며, 활성화 또는 테스트 시 필요합니다 |
| Send Test | 테스트 전송 1건을 보냄 | 최신 테스트가 Delivery Logs에 표시됩니다 |
| Delivery Logs | 최근 전송 상태와 페이로드 | 페이지당 10개 기록과 상태, 시도 횟수, HTTP 상태, 응답 본문, 페이로드 세부 정보 및 페이지 탐색이 표시됩니다 |
시작하기 전에
다음 기본 사항을 확인하세요.
-
settings:write권한이 있습니다 - 수신자 URL을 알고 있습니다
- 고정 인증 헤더를 알고 있습니다
- HMAC 서명 비밀값이 있습니다
- 수신자가 필요로 하는 게스트 필드를 알고 있습니다
저장된 헤더 값과 HMAC 서명 비밀값은 저장 후에도 계속 표시됩니다. 비밀값을 교체해야 할 때 새 값을 입력하세요.
전송 시점
게스트 검증이 성공하면 AVA가 웹훅을 전송합니다.
이벤트 이름은 guest_verified입니다.
PMS 동기화가 실패하면 AVA는 웹훅을 전송하지 않습니다.
요청은 JSON POST를 사용합니다. AVA는 모든 전송에 고정 헤더를 포함합니다.
웹훅 설정
켜기
-
Settings → Outbound Webhook으로 이동합니다.
-
Enabled를 켭니다.
-
Webhook URL을 입력합니다.
-
Save를 클릭합니다.
✓ AVA가 이후 전송을 위해 엔드포인트를 저장합니다.
사용자 정의 헤더 추가
수신자가 고정 인증을 요구할 때 헤더를 사용합니다.
AVA는 모든 JSON POST에 이 헤더를 포함합니다.
예를 들어 Authorization: token api_key:api_secret를 보낼 수 있습니다.
-
Add를 클릭합니다.
-
헤더 이름을 입력합니다.
-
헤더 값을 입력합니다.
-
민감한 값에는 Secret을 켭니다.
-
Save를 클릭합니다.
✓ 저장된 헤더 값은 저장 후에도 계속 표시됩니다.
페이로드 필드 선택
Payload Fields 카드에서 수신자에게 필요한 필드를 선택합니다. 카탈로그에는 예약 필드와 Settings → Check-In → Registration Form의 모든 필드가 포함됩니다. 마케팅 동의는 이 체크리스트에 포함되지 않습니다.
-
전송할 각 필드를 선택합니다.
-
수신자에게 필요하지 않은 필드는 선택 해제합니다.
-
Save를 클릭합니다.
✓ 이후 전송에는 선택한 필드만 표시됩니다.
사용 가능한 페이로드 필드
| 그룹 | AVA의 필드 | JSON 속성 |
|---|---|---|
| 예약 | 확인 번호 | reservation.confirmationNumber |
| 예약 | 도착 날짜 | reservation.arrivalDate |
| 예약 | 출발 날짜 | reservation.departureDate |
| 게스트 | 이름 | guest.firstName |
| 게스트 | 성 | guest.lastName |
| 게스트 | 이메일 | guest.email |
| 게스트 | 전화번호 | guest.phone |
| 게스트 | 국적 | guest.nationality |
| 게스트 | 문서 번호 | guest.documentNumber |
| 게스트 | 생년월일 | guest.birthDate |
| 게스트 | 우편번호 | guest.postalCode |
| 게스트 | 거주 국가 | guest.countryCode |
| 게스트 | 주소 | guest.addressLine |
| 게스트 | 도시 | guest.cityName |
| 게스트 | 주 또는 도 | guest.stateProv |
| 게스트 | 숙박 목적 | guest.purposeOfStay |
| 게스트 | 예상 도착 시간 | guest.preCheckInTime |
| 게스트 | 성별 | guest.gender |
| 게스트 | 직업 | guest.occupation |
| 게스트 | 출발지 | guest.placeOfDeparture |
| 게스트 | 다음 목적지 | guest.nextDestination |
| 게스트 | 출발 시간 | guest.departureTime |
선택한 필드가 비어 있으면 AVA가 JSON에서 해당 속성을 생략할 수 있습니다. 숙박 목적 및 예상 도착 시간에는 저장된 체크인 값을 사용할 수 있습니다. AVA는 주소 구성 요소를 결합하여 출발지와 다음 목적지를 만듭니다. 게스트가 현재 주소를 선택하면 AVA는 해당 주소를 목적지에 사용합니다.
마케팅 동의 상태 확인
Marketing consent 카드에는 네 가지 값이 표시됩니다.
- Guest prompt — 게스트에게 마케팅 옵트인을 표시하는지 여부
- Collection setting — PMS에서 사용하는 동의 모델
- Registration field — Marketing consent가 표시되는지 여부
- Webhook payload — AVA가
marketingConsent를 포함하는지 여부
Payload Fields 체크리스트는 이 값을 변경하지 않습니다.
-
상세 동의에는 Promotional Mailing List를 활성화합니다.
-
일반 동의에는 Show marketing email opt-in during signature를 활성화합니다.
-
Settings → Check-In → Registration Form으로 이동합니다.
-
Marketing consent에서 Show to를 All guests로 설정합니다.
-
두 설정 페이지를 모두 저장합니다.
✓ 두 가지 전제 조건이 준비되면 상태 카드에 Included가 표시됩니다. ✓ AVA는 게스트의 선택에 따라
true또는false를 전송합니다.
옵트인이 비활성화되어 있거나 필드가 숨겨져 있으면 AVA는 marketingConsent를 생략합니다.
전화번호 및 이메일 연락처 동의만으로는 마케팅 동의가 활성화되지 않습니다.
재시도 횟수와 서명 비밀값 설정
일시적인 전송 실패에는 재시도를 사용합니다. 수신자가 각 페이로드를 검증할 수 있도록 서명 비밀값을 설정합니다.
-
Max attempts에 값을 입력합니다.
-
1~10 사이의 값을 사용합니다.
-
HMAC signing secret을 입력합니다.
-
Save를 클릭합니다.
✓ AVA는 429, 5xx 및 시간 초과 실패를 재시도합니다. ✓ 검증 및 인증 오류는 재시도하지 않고 로그에 남습니다.
저장된 비밀값 교체
헤더 비밀값이나 서명 비밀값이 이미 있을 때 사용합니다. 현재 저장된 값이 해당 필드에 직접 표시됩니다.
-
헤더 또는 HMAC 필드에서 현재 값을 선택합니다.
-
새 값을 입력합니다.
-
Save를 클릭합니다.
✓ 저장 후 새 값이 표시되며 이후 전송에 적용됩니다.
테스트 전송 보내기
설정을 저장한 후 테스트 전송을 사용합니다. 테스트에는 가장 최근에 저장된 구성이 사용됩니다. 저장된 HMAC 서명 비밀값도 사용됩니다.
-
Send Test를 클릭합니다.
-
성공 메시지가 표시될 때까지 기다립니다.
-
Delivery Logs를 열어 새 행이 나타나는지 확인합니다.
✓ 가장 최근 행에는 test delivery가 표시됩니다.
페이지에서 무엇이든 변경했다면 테스트를 보내기 전에 저장하세요. 저장된 변경 사항이 모두 반영될 때까지 AVA는 테스트 버튼을 비활성화합니다.
전송 로그 검토
전송 로그를 통해 최근 시도를 확인할 수 있습니다. 각 페이지에는 10개의 행이 표시됩니다. 각 행에는 전송 상태, 타임스탬프, 시도 횟수, HTTP 상태 및 세부 정보가 표시됩니다. 전체 요청 페이로드와 응답 본문도 열어볼 수 있습니다. 페이지 컨트롤을 사용하여 이전 및 이후 전송 사이를 이동합니다.
| 상태 | 의미 |
|---|---|
| delivered | 수신자가 전송을 수락했습니다 |
| processing | AVA가 아직 전송을 처리 중입니다 |
| retrying | AVA가 나중에 다시 시도합니다 |
| pending | AVA가 전송을 대기열에 넣었습니다 |
| failed | AVA가 전송 재시도를 중지했습니다 |
-
Refresh delivery logs를 클릭하여 현재 페이지를 다시 불러옵니다.
-
결과가 더 있으면 First page, Previous, Next 또는 Last page를 사용합니다.
-
행을 열어 응답 세부 정보를 검토합니다.
-
전송된 JSON이 필요하면 View request payload를 펼칩니다.
-
수신자가 반환한 정확한 응답 본문을 확인하려면 View response를 펼칩니다.
✓ 여러 페이지가 있으면 페이지 카운터에 Page X of Y가 표시됩니다. ✓ 첫 페이지 또는 마지막 페이지에 도달할 때까지 컨트롤을 사용할 수 있습니다.
전송 로그에는 정확한 요청 페이로드와 수신자가 반환한 응답 본문이 표시됩니다. 페이로드에는 게스트 데이터가 포함될 수 있으므로 문제를 해결할 때만 세부 정보를 펼치세요.
문제 해결
페이지가 로드되지 않음
보이는 내용: Unable to load outbound webhook settings가 표시됩니다.
해결 방법:
- Retry를 클릭합니다.
- 페이지를 새로 고칩니다.
- 올바른 숙박 시설에 있는지 확인합니다.
- 필요한 경우 다시 로그인한 후 다시 시도합니다.
웹훅을 켤 때 저장 실패
보이는 내용: Enabled를 켠 후 저장에 실패합니다.
해결 방법:
- HMAC signing secret을 입력합니다.
- 다시 저장합니다.
- 이미 값이 있다면 지우지 말고 교체합니다.
Send Test가 계속 비활성화됨
보이는 내용: 페이지를 편집한 후 Send Test가 비활성화됩니다.
해결 방법:
- 먼저 Save를 클릭합니다.
- 성공 메시지가 표시될 때까지 기다립니다.
- Send Test를 다시 시도합니다.
- settings 권한이 있는지 확인합니다.
웹훅 URL이 거부됨
보이는 내용: 일부 대상 URL에서 저장 또는 테스트가 실패합니다.
해결 방법:
- 공개 HTTPS URL을 사용합니다.
- 사설, 예약, 루프백 및 사이트 로컬 주소를 제거합니다.
- 공개 수신자로 다시 시도합니다.
전송 로그가 비어 있음
보이는 내용: Delivery Logs에 아직 행이 표시되지 않습니다.
해결 방법:
- Send Test를 클릭합니다.
- 게스트 검증 이벤트가 발생할 때까지 기다립니다.
- Refresh delivery logs를 클릭합니다.
- 이전 전송이 있을 것으로 예상되면 페이지 카운터와 페이지 컨트롤을 확인합니다.
- 다음 조건을 충족하는 체크인 후 다시 확인합니다.
- 이전 전송으로 빠르게 이동해야 하면 Last page를 사용합니다.
새 등록 필드가 표시되지 않음
보이는 내용: 등록 필드가 Payload Fields에 표시되지 않습니다.
해결 방법:
- Settings → Outbound Webhook을 새로 고칩니다.
- 오류 없이 페이지가 로드되었는지 확인합니다.
- 위의 Payload Fields Available 표에서 해당 필드를 확인합니다.
- Settings → Check-In → Registration Form을 엽니다.
- 게스트가 값을 입력해야 한다면 Show to를 All guests로 설정합니다.
- 등록 양식을 저장하고 웹훅 페이지를 다시 로드합니다.
표시 여부 설정은 게스트 데이터 수집을 제어합니다. 이 설정은 필드가 웹훅 카탈로그에 표시되는지 여부를 제어하지 않습니다.
페이로드에 마케팅 동의가 없음
보이는 내용: 웹훅에 marketingConsent가 포함되지 않습니다.
해결 방법:
- Settings → Check-In → Card & Consent를 엽니다.
- 올바른 게스트 대상 마케팅 옵트인을 활성화합니다.
- Settings → Check-In → Registration Form을 엽니다.
- Marketing consent에서 Show to를 All guests로 설정합니다.
- 두 설정 페이지를 모두 저장합니다.
- 상태 카드에 Included가 표시되는지 확인합니다.
- 새로운 게스트 검증을 완료합니다.
게스트가 옵트인 또는 필드를 볼 수 없으면 AVA는 이 속성을 생략합니다. 설정이 표시되는데도 속성이 계속 누락되면 지원팀에 문의하세요.
아직도 해결되지 않나요?
다음과 같은 경우 success@vouch-technologies.com으로 문의하세요.
- ❌ 다시 시도한 후에도 페이지가 로드되지 않음
- ❌ HMAC 서명 비밀값을 추가한 후 저장에 실패함
- ❌ 테스트 전송이 로그에 표시되지 않음
다음 정보를 포함하세요.
- 사용 중인 수신자 URL
- 추가한 헤더 이름
- 비밀값과 게스트 데이터를 마스킹한 Delivery Logs 카드 스크린샷