웹훅 이벤트

모든 웹훅 이벤트, 발생 시점, 정확한 페이로드를 설명합니다.

고급 사용자용

이 페이지는 ITB 웹훅을 연동하는 개발자를 위한 기술 참고 자료입니다. 웹훅 엔드포인트를 설정하려는 것뿐이라면 웹훅 가이드부터 시작하세요.

이벤트 봉투

모든 웹훅 전송은 JSON 본문이 담긴 HTTP POST 요청입니다. 모든 이벤트는 동일한 최상위 봉투를 공유합니다:

필드	타입	설명
`id`	string	`evt_` 접두사가 붙은 고유 이벤트 ID(16진수 32자). 멱등성 키로 사용하세요 — 같은 이벤트가 두 번 이상 전송될 수 있습니다
`type`	string	이벤트 이름, 예: `order.approved`
`apiVersion`	string	날짜 기반 페이로드 버전. 현재는 `2026-07-01`
`createdAt`	string	이벤트가 발생한 시각 (ISO 8601)
`account.uid`	string	이벤트가 속한 계정(소유자) ID
`account.companyName`	string	설정된 경우 회사 이름
`data`	object	이벤트가 속한 리소스의 스냅샷 (아래 이벤트별 섹션 참고)
`changes`	object	일부 이벤트에만 존재 — 변경된 필드의 `previous` 및 `current` 스냅샷

{
  "id": "evt_9f2c4b7a1d3e5f60718293a4b5c6d7e8",   // idempotency key
  "type": "order.approved",                        // event name
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": {
    "uid": "abc123",
    "companyName": "Acme Home Services"
  },
  "data": { /* resource snapshot — see below */ },
  "changes": {                                     // only on *.approved, *.completed,
    "previous": { "status": "new" },               // *.status_changed, *.rescheduled
    "current": { "status": "approved" }
  }
}

각 전송에는 웹훅 가이드에서 설명하는 서명 헤더(webhook-id, webhook-timestamp, webhook-signature)와 함께 webhook-event 요청 헤더에도 이벤트 이름이 담겨 있습니다.

이벤트 목록

이벤트	발생 시점	`changes` 필드
`order.created`	새 Order이(가) 생성될 때 — 대시보드, 모바일 앱, 또는 온라인 예약 페이지에서	—
`order.approved`	Order의 상태가 승인됨이 될 때(승인된 상태로 생성된 경우 포함)	`status`
`order.completed`	Order의 상태가 완료가 될 때	`status`
`order.rescheduled`	승인됨 Order의 예약 날짜/시간이 변경될 때	`appointmentDateTime`
`order.status_changed`	`order.approved` 및 `order.completed`와 함께 발생하며, 승인됨 Order이(가) 이전 상태로 돌아갈 때도 발생	`status`
`invoice.paid`	Order이(가) 결제됨으로 표시될 때(`paid` 플래그가 처음으로 `true`가 될 때)	—
`report.published`	Order이(가) 처음으로 결제 완료 및 계약서 서명 상태가 모두 될 때 — Report이(가) 공개되는 시점	—

페이로드의 상태 값은 원시 저장 값입니다(draft, new, read, approved, complete, archived) — 주문 상태를 참고하세요.

필드 이름은 업종별로 바뀌지 않습니다

페이로드 필드 이름은 모든 업종에서 동일합니다. 예를 들어 Inspection Type는 화면에서 업종에 따라 어떻게 표시되든 항상 inspectionType이라는 필드로 전송됩니다.

주문 이벤트 — `data` 페이로드

order.created, order.approved, order.completed, order.rescheduled, order.status_changed는 모두 data에 동일한 Order 스냅샷을 전송합니다:

{
  "id": "req_abc123",                              // order ID
  "status": "approved",                            // see Order Statuses reference
  "appointmentDateTime": "2026-08-01T13:00:00.000Z",
  "inspectionType": "Buyer Inspection",            // your service category name
  "streetAddress": "123 Main St",
  "city": "Springfield",
  "region": "IL",
  "postalCode": "62701",
  "country": "US",
  "timezone": "America/Chicago",
  "contactName": "Jane Buyer",
  "contactEmail": "jane@example.com",
  "contactPhone": "(555) 123-4567",
  "contactType": "client",
  "totalPrice": 450,
  "totalTime": 120,                                // duration in minutes
  "paid": false,
  "agreementSigned": true,
  "assignedInspectors": ["uid1", "uid2"],          // assigned team member IDs
  "requestDateTime": "2026-07-20T09:15:00.000Z",   // when the order was created
  "approvedDateTime": "2026-07-21T10:00:00.000Z",
  "completedDateTime": "2026-08-01T16:30:00.000Z"
}

날짜 필드는 ISO 8601 문자열입니다. 값이 없는 필드는 null로 전송되는 대신 페이로드에서 생략됩니다.

주문 이벤트별 `changes`

order.approved — changes.previous.status / changes.current.status (current는 항상 "approved")
order.completed — changes.previous.status / changes.current.status (current는 항상 "complete")
order.status_changed — changes.previous.status / changes.current.status
order.rescheduled — changes.previous.appointmentDateTime / changes.current.appointmentDateTime (ISO 8601 문자열)
order.created — changes 필드 없음

승인은 두 개의 이벤트를 발생시킵니다

Order을(를) 승인하면 order.approved와 order.status_changed가 모두 전송됩니다. 완료 처리하면 order.completed와 order.status_changed가 모두 전송됩니다. 두 전송을 모두 받고 싶지 않다면 하나만 구독하세요.

Order의 paid 플래그가 처음으로 true가 될 때 발생합니다. data 페이로드는 위에 표시된 것과 동일한 Order 스냅샷입니다 — 청구서 객체가 아닙니다. 청구서 고유 필드(청구서 번호, 결제 금액, 결제 방법)는 없습니다. totalPrice와 paid: true 플래그를 사용하거나 API에서 청구서 세부 정보를 가져오세요. changes 필드는 전송되지 않습니다.

`report.published` — `data` 페이로드

Order이(가) 처음으로 결제 완료 및 계약서 서명 상태가 모두 될 때 발생합니다 — 게시된 Report이(가) 고객에게 공개되는 시점입니다. data 페이로드는 위에 표시된 Order 스냅샷에 하나의 추가 필드가 더해진 것입니다:

{
  "orderId": "req_abc123",   // same as data.id — the order this report belongs to
  "id": "req_abc123",
  "status": "complete"
  // …all other order snapshot fields
}

changes 필드는 전송되지 않습니다. 페이로드에는 보고서 URL이 포함되지 않습니다.

구독은 가능하지만 아직 발생하지 않는 이벤트

엔드포인트 편집기에는 order.updated, invoice.created, contact.created, contact.updated도 나열되어 있습니다. 이 이벤트 이름들은 예약되어 있어 선택할 수 있지만, 현재 계정 활동으로는 생성되지 않습니다 — 이 이벤트만 구독한 엔드포인트는 전송을 받지 못합니다. 향후 발생하게 되면 표준 봉투를 사용하며, data 필드는 아직 정의되지 않았습니다.

테스트 이벤트 — `webhook.test`

엔드포인트에서 테스트를 클릭하면 webhook.test 이벤트가 전송됩니다:

{
  "id": "evt_test_5f0e…",        // prefixed evt_test_
  "type": "webhook.test",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": { "uid": "abc123" },
  "data": {
    "message": "This is a test webhook event.",
    "timestamp": "2026-07-28T14:30:00.000Z"
  }
}

테스트 이벤트는 서명되지 않습니다 — 서명 헤더 대신 X-Webhook-Test: true 헤더가 포함됩니다. 수신 서버는 서명 검증 없이 이를 받아들여야 합니다(또는 이 헤더를 인식하여 테스트에 대해서만 검증을 건너뛰어야 합니다).

전송에 응답하기

전송을 확인하려면 10초 이내에 2xx 상태로 응답하세요.
5xx 응답과 타임아웃은 일시적인 것으로 간주되어 전송이 재시도됩니다.
그 외의 4xx 응답은 영구적인 것으로 간주되어 해당 전송은 재시도되지 않습니다.
410 Gone으로 응답하면 ITB에 전송을 중단하라고 알립니다: 엔드포인트가 즉시 비활성화됩니다.

엔드포인트 한도, 반복 실패 시 자동 비활성화, 전송 이력, 서명 검증은 웹훅 가이드에서 다룹니다.