> ## 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.

# Webhook Events

> Describes the payload format of Bolta webhook events and their behavior by issuance status.

<Note>
  Some links point to the service guide, which is currently available in Korean only.
</Note>

## Webhook Overview

Bolta asynchronously sends an issuance-success or issuance-failure notification to your registered webhook URL. Delivery time varies by environment, and live-key events may take approximately 10 minutes.

Events are delivered as JSON via HTTP POST. For security reasons, only HTTPS communication is supported.

> For webhook URL setup, see the [Webhook Connection Guide](/docs/developer-center/webhook-connection). The test and live environments must be registered separately.

## Firewall Settings

If the server that receives webhooks runs a firewall, add the IP address below to your inbound allowlist. It applies to both the test and live environments.

* `43.201.136.252`

## Tax Invoice Event Types

| Event Type                     | Description                               |
| ------------------------------ | ----------------------------------------- |
| `TAX_INVOICE_ISSUANCE_SUCCESS` | When a tax invoice is issued successfully |
| `TAX_INVOICE_ISSUANCE_FAILURE` | When a tax invoice fails to be issued     |

## Tax Invoice Payload

### Issuance Success

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

| Field                | Type   | Description                 |
| -------------------- | ------ | --------------------------- |
| `eventType`          | string | Event type                  |
| `data.issuanceKey`   | string | Issuance request identifier |
| `data.taxInvoiceUrl` | string | Tax invoice URL             |

### Issuance Failure

```json theme={"dark"}
{
  "eventType": "TAX_INVOICE_ISSUANCE_FAILURE",
  "data": {
    "issuanceKey": "IssuanceKey_0FE29D3930EF0C6F01J0XQ6WVFN3K9SB99Q6T13S50",
    "cause": {
      "code": "NOT_FOUND_CERTIFICATE",
      "message": "The certificate is not registered."
    }
  }
}
```

| Field                | Type   | Description                 |
| -------------------- | ------ | --------------------------- |
| `eventType`          | string | Event type                  |
| `data.issuanceKey`   | string | Issuance request identifier |
| `data.cause.code`    | string | Error code                  |
| `data.cause.message` | string | Error description           |

## Cash Receipt Event Types

Cash receipt issuance and cancellation are asynchronous. The API sends the final result in one of the following events.

| Event Type                         | Description            |
| ---------------------------------- | ---------------------- |
| `CASH_RECEIPT_ISSUED`              | Issuance succeeded     |
| `CASH_RECEIPT_ISSUE_FAILED`        | Issuance failed        |
| `CASH_RECEIPT_CANCELED`            | Cancellation succeeded |
| `CASH_RECEIPT_CANCEL_FAILED`       | Cancellation failed    |
| `CASH_RECEIPT_EXTERNALLY_CANCELED` | Canceled outside Bolta |

## Cash Receipt Payload

### Issuance Success

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_ISSUED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cashReceiptApprovalNumber": "123456789012"
  }
}
```

| Field                            | Type   | Description                  |
| -------------------------------- | ------ | ---------------------------- |
| `eventType`                      | string | Event type                   |
| `data.issuanceKey`               | string | Issuance key                 |
| `data.cashReceiptApprovalNumber` | string | Cash receipt approval number |

### Issuance Failure

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_ISSUE_FAILED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cause": {
      "code": "INVALID_RECIPIENT_IDENTIFIER",
      "message": "Check the cash receipt payment method information."
    }
  }
}
```

| Field                | Type   | Description                |
| -------------------- | ------ | -------------------------- |
| `eventType`          | string | Event type                 |
| `data.issuanceKey`   | string | Issuance key               |
| `data.cause.code`    | string | Failure code               |
| `data.cause.message` | string | Failure reason description |

### Cancellation Success

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_CANCELED",
  "data": {
    "issuanceKey": "9XK21ABC5KOAEIPGK8U6UO05I3EAQPLI8OE78Z1Q",
    "originalIssuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I"
  }
}
```

| Field                      | Type   | Description                                   |
| -------------------------- | ------ | --------------------------------------------- |
| `eventType`                | string | Event type                                    |
| `data.issuanceKey`         | string | Issuance key for the cancellation request     |
| `data.originalIssuanceKey` | string | Original issuance key of the canceled receipt |

### Cancellation Failure

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_CANCEL_FAILED",
  "data": {
    "issuanceKey": "9XK21ABC5KOAEIPGK8U6UO05I3EAQPLI8OE78Z1Q",
    "originalIssuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I",
    "cause": {
      "code": "ORIGINAL_ISSUANCE_FAILED",
      "message": "The original cash receipt issuance failed, so the cancellation request cannot be processed."
    }
  }
}
```

| Field                      | Type   | Description                                         |
| -------------------------- | ------ | --------------------------------------------------- |
| `eventType`                | string | Event type                                          |
| `data.issuanceKey`         | string | Issuance key for the cancellation request           |
| `data.originalIssuanceKey` | string | Original issuance key of the receipt being canceled |
| `data.cause.code`          | string | Failure code                                        |
| `data.cause.message`       | string | Failure reason description                          |

### Canceled Outside Bolta

Bolta sends this event when an issued cash receipt is canceled outside Bolta (for example, on Hometax or a payment gateway).

```json theme={"dark"}
{
  "eventType": "CASH_RECEIPT_EXTERNALLY_CANCELED",
  "data": {
    "issuanceKey": "MRK98JGC5KOAEIPGK8U6UO05I3EAQPLI8OE78A3I"
  }
}
```

| Field              | Type   | Description                                             |
| ------------------ | ------ | ------------------------------------------------------- |
| `eventType`        | string | Event type                                              |
| `data.issuanceKey` | string | Issuance key of the cash receipt canceled outside Bolta |

## Webhook Delivery Time

| Environment        | Delivery Time                                       |
| ------------------ | --------------------------------------------------- |
| Test key (`test_`) | 10–30 seconds after the issuance request            |
| Live key (`live_`) | Approximately 10 minutes after the issuance request |

## Checking Webhook Logs

You can review the success/failure history of sent webhooks in the [Developer Center > Event Logs](/docs/developer-center/webhook-log).