> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bolta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 웹훅 이벤트

> 볼타 웹훅 이벤트의 페이로드 형식과 발행 상태별 동작을 안내합니다.

## 웹훅 개요

볼타는 세금계산서 발행 상태가 변경될 때 등록된 웹훅 URL로 실시간 알림을 전송합니다.

이벤트는 HTTP POST 메서드로 전달되는 JSON이며, 보안상의 이유로 HTTPS 통신만 지원합니다.

> 웹훅 URL 설정은 [웹훅 연결 가이드](/docs/developer-center/webhook-connection)를 참고하세요. 테스트 환경과 라이브 환경은 각각 별도로 등록해야 합니다.

## 웹훅 이벤트 타입

| 이벤트 타입                         | 설명                 |
| ------------------------------ | ------------------ |
| `TAX_INVOICE_ISSUANCE_SUCCESS` | 전자세금계산서 발행에 성공했을 때 |
| `TAX_INVOICE_ISSUANCE_FAILURE` | 전자세금계산서 발행에 실패했을 때 |

## 웹훅 페이로드

### 발행 성공

```json theme={"dark"}
{
  "eventType": "TAX_INVOICE_ISSUANCE_SUCCESS",
  "data": {
    "issuanceKey": "IssuanceKey_0FE29D3930EF0C6F01J0XQ6WVFN3K9SB99Q6T13S50",
    "taxInvoiceUrl": "https://app.bolta.io/taxInvoices/..."
  }
}
```

| 필드                   | 타입     | 설명         |
| -------------------- | ------ | ---------- |
| `eventType`          | string | 이벤트 타입     |
| `data.issuanceKey`   | string | 발행 요청 식별번호 |
| `data.taxInvoiceUrl` | string | 세금계산서 URL  |

### 발행 실패

```json theme={"dark"}
{
  "eventType": "TAX_INVOICE_ISSUANCE_FAILURE",
  "data": {
    "issuanceKey": "IssuanceKey_0FE29D3930EF0C6F01J0XQ6WVFN3K9SB99Q6T13S50",
    "cause": {
      "code": "NOT_FOUND_CERTIFICATE",
      "message": "공동인증서가 등록되지 않았습니다."
    }
  }
}
```

| 필드                   | 타입     | 설명         |
| -------------------- | ------ | ---------- |
| `eventType`          | string | 이벤트 타입     |
| `data.issuanceKey`   | string | 발행 요청 식별번호 |
| `data.cause.code`    | string | 에러 코드      |
| `data.cause.message` | string | 에러 설명      |

## 웹훅 발송 시간

| 환경              | 발송 소요 시간        |
| --------------- | --------------- |
| 테스트 키 (`test_`) | 발행 요청 후 10\~30초 |
| 라이브 키 (`live_`) | 발행 요청 후 약 10분   |

## 웹훅 로그 확인

전송된 웹훅의 성공/실패 이력은 [개발자센터 > 이벤트 로그](/docs/developer-center/webhook-log)에서 확인할 수 있습니다.