---
title: "Receive Webhook"
method: POST
path: "/v1/billing/webhooks/{provider}"
tags: ["Billing Webhooks"]
---

# Receive Webhook

`POST /v1/billing/webhooks/{provider}`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/billing/webhooks/{provider}`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

PG 웹훅 수신 - 받은 뒤 7단계로 처리한다.

## Path parameters

- `provider` string, required

## Headers

- `X-Env-Scope` 'sandbox' | 'real_test' | 'production', nullable: 외부 PG 가 보내는 환경 힌트입니다(필수가 아닙니다). 값은 production, real_test, sandbox 중 하나이고, 보내면 그 환경의 서명만 검증합니다. 보내지 않으면 production, real_test, sandbox 순서로 시도해 서명이 맞는 환경을 고릅니다. 목록 밖의 값은 HTTP 400 WEBHOOK_PAYLOAD_INVALID 로 거절합니다.

## Response `200`

Successful Response

- WebhookAckResponse: PG 웹훅 수신 ACK 응답. 외부 응답은 단순 ack만 반환한다: - 정상 처리: 200 OK + `{ "received": true }` - 중복 수신: 200 OK + `{ "received": true }` (SKIPPED_DUPLICATE 내부 분류) - 영구 오류: 200 OK + `{ "received": true }` (FAILED 내부 분류; PG 재전송 폭주 방지) PG가 비-2xx 응답 시 재전송하므로, 비즈 처리 실패가 일시적이지 않은 **영구 오류**라면 200 OK + `processing_status='FAILED'` 적재로 재전송 폭주를 막는다. 서명 실패/payload 오류는 본 DTO 대신 표준 오류 envelope으로 응답: - 401 WEBHOOK_SIGNATURE_INVALID - 400 WEBHOOK_PAYLOAD_INVALID - 503 PROVIDER_UNAVAILABLE (PG 자동 재전송 유도) 응답 시그니처는 PG 사업자별로 호환을 유지해야 하므로(PG 재시도 정책 보존), 필드 추가/제거/변경은 상위 계약과 이 docstring 을 함께 고치고 별도 결정을 거친다. 본 응답은 외부 노출 전용 — `billing_events.id`/`processing_status` 등 내부 식별자는 포함하지 않는다(증거 보존 + 운영 API 분리).
  - `received` true, required: 수신 확인. 잠금된 단일 값(`true`). PG 사업자 호환 보존 위해 변경 금지. false 반환 케이스는 정의되지 않으며, 영구 오류도 `received=true` + 내부 FAILED 분류.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)