Bolta Webhook

볼타가 정발행/수정발행 결과를 비동기로 통보합니다 (테스트 약 10~30초, 운영 약 10분 소요).

HTTP 요청

POST /ai/webhooks/bolta/{secret}
Content-Type: application/json

Path Parameters

파라미터	타입	필수	설명
`secret`	String	예	환경변수 `BOLTA_WEBHOOK_SECRET`와 일치해야 함. 불일치 시 403.

⚠️ 볼타가 custom HTTP header를 지원하지 않아 secret을 URL path에 둠. 글로브 측에서는 MDC 필터로 path 마스킹 처리.

Payload (성공)

{
  "eventType": "TAX_INVOICE_ISSUANCE_SUCCESS",
  "data": {
    "issuanceKey": "IssuanceKey_AB3C8B157DEA681E01KR2V4GF1W7HC79QEQ33FS9RF",
    "taxInvoiceUrl": "https://app.bolta.io/taxInvoices/..."
  }
}

Payload (실패)

{
  "eventType": "TAX_INVOICE_ISSUANCE_FAILURE",
  "data": {
    "issuanceKey": "IssuanceKey_xxxxxxxx",
    "cause": {
      "code": "INVALID_SUPPLIED_BUSINESS",
      "message": "사업자번호가 유효하지 않습니다"
    }
  }
}

처리 흐름 (서버)

URL의 secret 검증 (불일치 → 403)
issuanceKey로 DB 조회 (없으면 200 OK, 매칭 실패 로그)
멱등 체크: 이미 ISSUED/FAILED/CANCELLED/AMENDED면 스킵
SUCCESS → status=ISSUED + taxInvoiceUrl 저장
- Slack 알림 발송 (✅ 세금계산서 발행 완료 + 사업자번호, TaxInvoiceNotifyEvent.ISSUED)
FAILURE → status=FAILED + cause 저장
- Slack 알림 발송 (❌ 세금계산서 발행 실패 + 에러 코드, TaxInvoiceNotifyEvent.FAILED)

Slack 알림 종류 (4종)

Trigger	메시지	발생 위치
`REQUESTED`	📋 청구 접수	`TaxInvoiceService.issueNormal` 성공 직후
`ISSUED`	✅ 발행 완료	webhook SUCCESS 처리 시
`FAILED`	❌ 발행 실패	webhook FAILURE 처리 시
`AMENDED`	🔄 수정/취소 발행	`TaxInvoiceService.amendOrCancel` 성공 직후

채널은 slack.payment-alert.channel-id 설정 (test=C0A91KHKJA2, prod=C0B2TRJ7GRK).

주요 에러 코드 (FAILURE.cause.code)

코드	의미	대응
`INVALID_SUPPLIED_BUSINESS`	받는 측 사업자번호 무효	광고주에 재확인 요청
`INVALID_CERTIFICATE`	인증서 만료/폐기	글로브 인증서 갱신
`NOT_FOUND_CERTIFICATE`	인증서 미등록	볼타 콘솔 등록
`INTERNAL_SERVER_ERROR`	5xx	자동 재시도

볼타(Bolta) Webhook 수신