아웃바운드 웹훅 전송 설정
대부분의 호텔은 5~10분이면 완료됩니다.
이 가이드는 게스트 검증과 PMS 동기화가 끝난 뒤 JSON guest_verified 이벤트를 전송하는 방법을 안내합니다.
이동 경로: Settings → Outbound Webhook
모든 전송에는 X-Vouch-Signature가 포함됩니다.
수신 측에서는 페이로드를 신뢰하기 전에 이 헤더를 검증해야 합니다.
빠른 참고
| 설정 | 제어 항목 | 보이는 내용 |
|---|---|---|
| Enabled | 아웃바운드 웹훅 전송을 켜거나 끔 | 저장 후에도 토글이 켜진 상태로 유지됩니다 |
| Webhook URL | 전송 대상 URL | AVA가 수신자 URL을 허용합니다 |
| Headers | 수신 측용 고정 인증 헤더 | 비밀 값은 저장 후에도 마스킹됩니다 |
| Payload Fields | 전송할 게스트 필드 | 선택한 필드만 전송에 포함됩니다 |
| Max attempts | 실패한 전송의 재시도 횟수 | 값은 1~10 사이로 유지됩니다 |
| HMAC signing secret | 각 전송의 페이로드 서명 | 켜져 있거나 테스트 중일 때 비밀값 없이는 저장할 수 없습니다 |
| Send Test | 테스트 전송 1건 발송 | 최신 테스트 결과가 Delivery Logs에 표시됩니다 |
| Delivery Logs | 최근 전송 상태와 페이로드 | 상태, 시도 횟수, HTTP 상태, 응답 본문, 페이로드 세부 정보를 확인할 수 있습니다 |
시작하기 전에
다음 항목을 확인하세요.
-
settings:write권한이 있습니다 - 수신자 URL을 알고 있습니다
- 고정 인증 헤더를 알고 있습니다
- 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 카드에서 선택합니다. 일반적으로 확인 번호, 날짜, 게스트 연락처 정보, 국적, 문서 번호, 마케팅 동의가 포함됩니다.
-
전송할 각 필드를 선택합니다.
-
수신자가 필요로 하지 않는 필드는 선택 해제합니다.
-
Save를 클릭합니다.
✓ 이후 전송에는 선택한 필드만 표시됩니다.
재시도 횟수와 서명 비밀값 설정
일시적인 전송 실패에는 재시도를 사용합니다. 수신자가 각 페이로드를 검증할 수 있도록 서명 비밀값을 설정합니다.
-
Max attempts에 값을 입력합니다.
-
1~10 사이의 값을 사용합니다.
-
HMAC signing secret을 입력합니다.
-
Save를 클릭합니다.
✓ AVA는 429, 5xx, 시간 초과 실패를 다시 시도합니다. ✓ 검증 및 인증 오류는 재시도하지 않고 로그에 남습니다.
저장된 비밀값 바꾸기
이미 헤더 비밀값이나 서명 비밀값이 있을 때 사용합니다. 이전 값은 확인할 수 없습니다.
-
마스킹된 비밀값 옆의 연필 아이콘을 클릭합니다.
-
새 값을 입력합니다.
-
Save를 클릭합니다.
✓ 저장된 값은 저장 후에도 계속 마스킹됩니다.
테스트 전송 보내기
설정을 저장한 뒤 테스트 전송을 사용합니다. 테스트는 가장 최근에 저장한 구성을 사용합니다. 저장된 HMAC 서명 비밀값도 함께 사용합니다.
-
Send Test를 클릭합니다.
-
성공 메시지가 나올 때까지 기다립니다.
-
Delivery Logs를 열어 새 행이 표시되는지 확인합니다.
✓ 가장 최근 행에는 test delivery가 표시됩니다.
페이지에서 무엇이든 변경했다면 테스트를 보내기 전에 먼저 저장하세요. 저장되지 않은 변경 사항이 있으면 AVA가 테스트 버튼을 비활성화합니다.
전송 로그 검토
전송 로그로 최근 25번의 시도를 확인할 수 있습니다. 각 행에는 전송 상태, 시각, 시도 횟수, HTTP 상태, 세부 정보가 표시됩니다. 요청 페이로드와 응답 본문도 열어볼 수 있습니다.
| 상태 | 의미 |
|---|---|
| delivered | 수신자가 전송을 수락했습니다 |
| processing | AVA가 아직 전송을 처리 중입니다 |
| retrying | AVA가 나중에 다시 시도합니다 |
| pending | AVA가 전송을 대기열에 넣었습니다 |
| failed | AVA가 더 이상 재시도하지 않습니다 |
- Refresh delivery logs를 클릭해 목록을 다시 불러옵니다.
- 행을 열어 응답 세부 정보를 검토합니다.
- 보낸 JSON이 필요하면 View request payload를 펼칩니다.
민감한 값은 로그 화면에서도 마스킹된 상태로 유지됩니다. 페이로드 세부 정보는 문제 해결용으로만 사용하세요.
문제 해결
페이지가 열리지 않음
보이는 내용: Unable to load outbound webhook settings가 표시됩니다.
해결:
- Retry를 클릭합니다.
- 페이지를 새로고칩니다.
- 올바른 property에 있는지 확인합니다.
- 필요하면 다시 로그인한 뒤 다시 시도합니다.
웹훅을 켤 때 저장이 실패함
보이는 내용: Enabled를 켠 뒤 저장이 실패합니다.
해결:
- HMAC signing secret을 입력합니다.
- 다시 저장합니다.
- 이미 값이 있었다면 지우지 말고 바꿉니다.
Send Test가 계속 비활성화됨
보이는 내용: 페이지를 수정한 뒤 Send Test가 비활성화됩니다.
해결:
- 먼저 Save를 클릭합니다.
- 성공 메시지를 기다립니다.
- Send Test를 다시 시도합니다.
- settings 권한이 있는지 확인합니다.
웹훅 URL이 거부됨
보이는 내용: 일부 대상 URL에서 저장 또는 테스트가 실패합니다.
해결:
- 공개 HTTPS URL을 사용합니다.
- 사설, 예약, 루프백, 사이트 로컬 주소를 제거합니다.
- 공개 수신자로 다시 시도합니다.
전송 로그가 비어 있음
보이는 내용: Delivery Logs에 아직 행이 없습니다.
해결:
- Send Test를 클릭합니다.
- 게스트 검증 이벤트가 발생할 때까지 기다립니다.
- Refresh delivery logs를 클릭합니다.
- 다음 적합한 체크인 이후 다시 확인합니다.
아직도 해결되지 않나요?
다음 경우 success@vouch-technologies.com으로 문의하세요.
- ❌ 다시 시도해도 페이지가 여전히 열리지 않음
- ❌ HMAC 서명 비밀값을 추가한 뒤 저장이 실패함
- ❌ 테스트 전송이 로그에 표시되지 않음
포함하면 좋은 정보:
- 사용 중인 수신자 URL
- 추가한 헤더 이름
- Delivery Logs 카드 스크린샷