Some links point to the service guide, which is in Korean.
Webhook Overview
Bolta asynchronously sends tax invoice and cash receipt issuance and cancellation results to your registered webhook URL. Bolta delivers events as JSON via HTTP POST and supports only HTTPS URLs on a public domain. Bolta does not send to IP addresses or internal network addresses.For webhook URL setup, see the Webhook Connection Guide. Register a URL for the test and live environments 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
Signature Verification
Bolta signs webhook requests using the Standard Webhooks specification. Verify the signature on your receiving server before you process an event.Get the Signing Secret
In the Developer Center, open the [Settings] tab under [Integrations] > [Webhooks], rotate the signing secret, and copy the new signing secret shown on the screen. The Developer Center shows the signing secret only once, when you rotate it. The signing secret starts withwhsec_ and is different from your API credential. The test and live environments have different signing secrets, so store one for each environment. Save the copied value as is in a server environment variable, and keep it out of browser code, logs, and repositories.
Request Headers
The signed content is
{webhook-id}.{webhook-timestamp}.{raw request body}, and the algorithm is HMAC-SHA256. The HMAC key is the Base64-decoded part of the signing secret after whsec_.
Verify Requests
Pass the copied signing secret as is to an official library. The library verifies the signature and the timestamp together.- Read the raw request body before you parse it as JSON. Re-serialized JSON does not match the signature.
- The library rejects requests whose timestamp is more than 5 minutes before or after the current time. Keep your server clock in sync and leave the timestamp check on.
- If
webhook-signaturecarries multiple signatures, the request passes when one of them matches. After a graceful rotation, Bolta signs with both the previous and the new secret for 24 hours. Bolta may still use the revoked secret to sign deliveries, including retries, for up to 1 minute after an emergency revocation. - Do not process a request that fails verification. Respond with
400.
Test
Register a receiving URL in the test environment, then issue a tax invoice or cash receipt with a test key. Bolta sends the webhook at least 10 seconds after it accepts the issuance request. Confirm that your server accepts a valid request, then confirm that it rejects a request with a modified body, a request with a missing header, and a request signed with a different secret. If the signature does not match, check the following:- You did not swap the test and live signing secrets
- You did not use the API credential instead of the signing secret
- You did not verify re-serialized JSON
- You updated the secret on your server after rotating it
Event Types by Product
Each product page carries the payload examples, field descriptions, and delivery timing.
Responses and Retries
Return a2xx response within 10 seconds. Bolta waits up to 5 seconds to connect and cancels the request if the response headers do not arrive within 10 seconds of the start of delivery. Bolta does not read the response body. If processing takes longer, respond first and process the event asynchronously.
Bolta treats any non-2xx response, connection failures, and timeouts as delivery failures. After a failure, Bolta follows the schedule below and makes up to 8 attempts, including the first delivery.
The actual wait varies by ±10% from the value in the table. The last attempt comes about 44 hours and 36 minutes after the first. On each retry, Bolta keeps the
webhook-id and the body and generates a new webhook-timestamp and signature.
If the 8th attempt fails, Bolta records the delivery as failed and stops retrying automatically. Check the result with the status API below.
Bolta does not follow redirects. It treats a 3xx response as a delivery failure and retries it, so register a URL that responds without a redirect.
You can receive the same event more than once or out of order. Record webhook-id as a unique key, and respond with 2xx without processing an event you have already received. Also guard business updates against duplicates with eventType and issuanceKey. Keep the idempotency records after automatic retries end.
