> ## Documentation Index
> Fetch the complete documentation index at: https://playcamp.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 웹훅 등록



## OpenAPI

````yaml /api_docs/openapi-ko.yaml post /v1/server/webhooks
openapi: 3.0.3
info:
  title: PlayCamp SDK API
  description: |
    PlayCamp SDK API - 게임 분석 및 크리에이터 캠페인 연동 API

    ## 필수 연동 API (Server API)
    캠페인 진행을 위해 반드시 연동해야 하는 API 3개:
    - `POST /v1/server/sponsors` - 유저가 크리에이터를 부스트
    - `POST /v1/server/coupons/validate` - 쿠폰 코드 유효성 검사
    - `POST /v1/server/payments` - 인게임 결제 등록

    ## 인증 방식
    - **Client API**: `Authorization: Bearer {CLIENT_KEY_ID}:{CLIENT_SECRET}`
    - **Server API**: `Authorization: Bearer {SERVER_KEY_ID}:{SERVER_SECRET}`

    ## 서버
    - **Live**: https://sdk-api.playcamp.io (실제 데이터)
    - **Sandbox**: https://sandbox-sdk-api.playcamp.io (테스트 데이터)

    ## 키 타입
    - **Client 키**: 게임 클라이언트용 (읽기 전용 - 캠페인, 크리에이터 조회)
    - **Server 키**: 게임 서버용 (읽기/쓰기 - 쿠폰 사용, 결제 등록 등)

    ## 테스트 모드 (isTest)
    캠페인 실행 전에 `isTest: true` 파라미터를 사용하여 API 연동을 테스트할 수 있습니다.
    - 요청 파라미터 검증은 실제와 동일하게 수행
    - 모의 데이터를 반환하며 실제 DB에 기록되지 않음
    - 캠페인 시작 전 Sandbox 환경에서 연동 검증 후, 실제 캠페인 시 `isTest` 파라미터 제거
  version: 1.1.0
  contact:
    name: PlayCamp Support
servers:
  - url: https://sdk-api.playcamp.io
    description: Live Server
  - url: https://sandbox-sdk-api.playcamp.io
    description: Sandbox Server
  - url: http://localhost:3001
    description: Local Live Server
  - url: http://localhost:3003
    description: Local Sandbox Server
security: []
tags:
  - name: Health
    description: 서버 상태 확인
  - name: Client Campaign
    description: 캠페인 조회 (Client API)
  - name: Client Creator
    description: 크리에이터 조회 (Client API)
  - name: Client Coupon
    description: 쿠폰 유효성 검사 (Client API)
  - name: Client Sponsor
    description: 부스트 상태 조회 — Sponsor API (Client API)
  - name: Server Campaign
    description: 캠페인 조회 (Server API)
  - name: Server Creator
    description: 크리에이터 조회 (Server API)
  - name: Server Coupon
    description: 쿠폰 관리 (Server API)
  - name: Server Sponsor
    description: 부스트 관리 — Sponsor API (Server API)
  - name: Server Payment
    description: 결제 관리 (Server API)
  - name: Server Playtime
    description: 플레이타임 세션 관리 (Server API)
  - name: Server Webhook
    description: 웹훅 관리 (Server API)
  - name: Server Webview
    description: WebView 관리 (Server API)
paths:
  /v1/server/webhooks:
    post:
      tags:
        - Server Webhook
      summary: 웹훅 등록
      operationId: serverCreateWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - eventType
                - url
              properties:
                eventType:
                  type: string
                  enum:
                    - coupon.redeemed
                    - payment.created
                    - payment.bulk_created
                    - sponsor.created
                    - sponsor.ended
                  description: |
                    웹훅 이벤트 타입:
                    - `coupon.redeemed`: 쿠폰 사용
                    - `payment.created`: 결제 생성
                    - `sponsor.created`: 부스트 생성 (Sponsor)
                url:
                  type: string
                  format: uri
                  description: 웹훅 수신 URL
                retryCount:
                  type: integer
                  default: 3
                  minimum: 0
                  maximum: 10
                  description: 실패 시 재시도 횟수
                timeoutMs:
                  type: integer
                  default: 5000
                  minimum: 1000
                  maximum: 30000
                  description: 타임아웃 (밀리초)
      responses:
        '201':
          description: 성공 (secret은 이 응답에서만 반환됨)
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookWithSecret'
      security:
        - ServerAuth: []
components:
  schemas:
    WebhookWithSecret:
      type: object
      description: 웹훅 생성 응답 (secret 포함)
      allOf:
        - $ref: '#/components/schemas/Webhook'
        - type: object
          properties:
            secret:
              type: string
              description: 웹훅 서명 검증용 시크릿 (생성 시에만 반환, 이후 조회 불가)
    Webhook:
      type: object
      description: 웹훅 설정 (secret은 생성 시에만 반환)
      properties:
        id:
          type: integer
        eventType:
          type: string
          enum:
            - coupon.redeemed
            - payment.created
            - payment.bulk_created
            - sponsor.created
            - sponsor.ended
        url:
          type: string
          format: uri
        isActive:
          type: boolean
        retryCount:
          type: integer
        timeoutMs:
          type: integer
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    ServerAuth:
      type: http
      scheme: bearer
      description: 'Server API Key (format: {keyId}:{secret})'

````