웹훅
계정에서 이벤트가 발생하면 다른 앱으로 데이터를 자동으로 전송하세요.
개요
웹훅을 사용하면 계정에서 무언가 발생할 때마다 다른 앱이나 서비스로 데이터를 자동으로 전송할 수 있습니다 — 예를 들어 새 Order이(가) 생성되거나, 청구서가 결제되거나, Report이(가) 게시될 때입니다. 대시보드를 직접 확인하는 대신, 웹훅이 실시간으로 사용 중인 도구에 업데이트를 전송합니다.
설정연동에서 웹훅을 관리합니다.
웹훅 엔드포인트 설정하기
엔드포인트 추가
엔드포인트 추가를 클릭합니다. 표시되는 대화 상자에 다음을 입력합니다:
| 항목 | 설명 |
|---|---|
| URL | 데이터를 받을 웹 주소 (연결하려는 앱이나 서비스에서 제공) |
| 설명 | 이 엔드포인트의 용도를 기억하는 데 도움이 되는 선택적 레이블 |
| 이벤트 | 알림을 트리거할 이벤트 선택 — 개별 이벤트를 선택하거나 전체를 구독할 수 있습니다 |
서명 비밀키 생성 및 복사
생성을 클릭합니다. 서명 비밀키가 표시됩니다 — 이는 수신하는 앱이 데이터가 여러분의 계정에서 온 것임을 확인할 수 있게 하는 보안 키입니다.
지금 비밀키를 복사하세요
서명 비밀키는 한 번만 표시됩니다. 복사하여 안전한 곳에 보관하세요. 분실한 경우 엔드포인트 설정에서 비밀키를 교체해야 합니다.
계정당 최대 10개의 웹훅 엔드포인트를 추가할 수 있습니다.
사용 가능한 이벤트
현재 전송되는 이벤트는 다음과 같습니다:
| 이벤트 | 트리거 조건 |
|---|---|
| 주문 생성됨 | 새 Order이(가) 계정에 추가됨 |
| 주문 승인됨 | Order이(가) 승인됨 |
| 주문 완료됨 | Order이(가) 완료로 표시됨 |
| 주문 일정 변경됨 | 승인된 Order의 예약 날짜/시간이 변경됨 |
| 주문 상태 변경됨 | Order이(가) 승인 또는 완료되거나 승인이 취소됨 |
| 청구서 결제됨 | 청구서가 결제됨으로 표시됨 — 온라인 결제 또는 수동 기록 |
| 보고서 게시됨 | Report이(가) 게시됨 |
엔드포인트 양식에는 주문 업데이트됨, 청구서 생성됨, 연락처 생성됨, 연락처 업데이트됨도 표시됩니다. 지금 구독할 수는 있지만 아직 전송되지 않습니다 — 향후 전송을 위해 예약되어 있습니다.
각 이벤트의 정확한 페이로드는 웹훅 이벤트를 참고하세요.
변하지 않는 이벤트 및 필드 이름
이벤트 이름과 페이로드 필드 이름은 모든 계정과 업종에서 동일하므로, 업종 설정을 변경해도 연동은 계속 작동합니다. 일부 페이로드 필드는 레거시 이름을 사용합니다(예: 서비스 카테고리를 뜻하는 inspectionType) — 이벤트 참고 자료를 확인하세요.
웹훅 테스트하기
엔드포인트를 생성한 후 테스트 이벤트를 전송하여 모든 것이 연결되었는지 확인할 수 있습니다:
목록에서 엔드포인트를 찾아 메뉴 버튼을 클릭합니다.
Send test event를 선택합니다. 샘플 이벤트가 엔드포인트 URL로 전송됩니다.
수신하는 앱에서 테스트 데이터가 도착했는지 확인합니다.
문제 해결
엔드포인트 비활성화
엔드포인트가 연속으로 8회 데이터 수신에 실패하면, 반복적인 실패를 막기 위해 자동으로 비활성화됩니다. 엔드포인트에 비활성 상태가 표시됩니다.
다시 활성화하려면:
- 수신 측의 문제를 해결합니다 (URL에 접근할 수 있고 올바르게 응답하는지 확인).
- 엔드포인트의 메뉴 버튼을 클릭하고 Enable을 선택합니다.
전달 기록 확인하기
엔드포인트의 메뉴 버튼을 클릭하고 View deliveries를 선택하면 최근 전달 시도 로그를 볼 수 있습니다. 각 항목에는 다음이 표시됩니다:
- 전달 성공 또는 실패 여부
- HTTP 응답 코드
- 전송된 시점
이벤트가 예상대로 도착하지 않을 때 무엇이 잘못되었는지 파악하는 데 도움이 됩니다.
보안
모든 웹훅 전달에는 요청 헤더에 서명이 포함됩니다. 개발자와 함께 맞춤 연동을 구축하는 경우, 서명 비밀키를 사용하여 수신 데이터가 실제로 여러분의 ITB 계정에서 온 것이며 변조되지 않았음을 확인할 수 있습니다.
관련 헤더는 다음과 같습니다:
| 헤더 | 용도 |
|---|---|
webhook-id | 이 이벤트의 고유 ID |
webhook-timestamp | 이벤트가 전송된 시점 (Unix 타임스탬프) |
webhook-signature | 확인에 사용하는 HMAC-SHA256 서명 |
개발자를 위한 안내
서명을 확인하려면 서명 비밀키를 사용하여 {timestamp}.{body} 문자열에 대해 HMAC-SHA256을 계산하고, (v1= 접두사를 제거한 후) 헤더의 서명과 비교합니다. 타이밍 공격을 막기 위해 상수 시간 비교를 사용하세요.
Zapier 및 Make와 함께 사용하기
Zapier나 Make(구 Integromat) 같은 자동화 플랫폼을 사용하는 경우, OAuth를 통해 ITB 계정에 연결하고 웹훅 이벤트를 자동으로 구독할 수 있습니다. 자동화 플랫폼의 앱 디렉토리에서 ITB 연동을 찾아보세요.