Webhook Events

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

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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).

{
  "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.

API Introduction

API Guides

Use Cases

SDK / No-code

Webhook Overview

Firewall Settings

Tax Invoice Event Types

Tax Invoice Payload

Issuance Success

Issuance Failure

Cash Receipt Event Types

Cash Receipt Payload

Issuance Success

Issuance Failure

Cancellation Success

Cancellation Failure

Canceled Outside Bolta

Webhook Delivery Time

Checking Webhook Logs

​Webhook Overview

​Firewall Settings

​Tax Invoice Event Types

​Tax Invoice Payload

​Issuance Success

​Issuance Failure

​Cash Receipt Event Types

​Cash Receipt Payload

​Issuance Success

​Issuance Failure

​Cancellation Success

​Cancellation Failure

​Canceled Outside Bolta

​Webhook Delivery Time

​Checking Webhook Logs

Webhook Overview

Firewall Settings

Tax Invoice Event Types

Tax Invoice Payload

Issuance Success

Issuance Failure

Cash Receipt Event Types

Cash Receipt Payload

Issuance Success

Issuance Failure

Cancellation Success

Cancellation Failure

Canceled Outside Bolta

Webhook Delivery Time

Checking Webhook Logs