주요 콘텐츠로 건너뛰기

구독 웹훅

Aghanim의 구독 웹훅은 구독 주기 이벤트를 통해 여러분의 게임에 알림을 제공하여 구독 기반 콘텐츠 및 서비스에 대한 플레이어 접근 권한을 관리할 수 있게 해줍니다.

웹훅 이벤트

이 웹훅 이벤트를 사용하여 구독 접근 권한을 부여, 확장 또는 취소할 수 있습니다.

이벤트발생 시기해야 할 일
subscription.activated구독이 활성화됩니다.플레이어에게 구독 혜택을 제공합니다.
subscription.updated구독 속성이 변경됩니다 (상태, 플랜 또는 청구 날짜).업데이트된 구독 데이터와 내부 상태를 동기화하십시오.
subscription.renewed정기 결제가 성공적으로 이루어집니다.effective_until을 업데이트하여 접근을 확장합니다. (선택 사항) 각 성공적인 갱신 시 보상을 제공하십시오 (적용되는 경우).
subscription.deactivated구독이 비활성화되었습니다너무 오래 걸려서 구독 혜택을 즉시 취소합니다.
Idempotency의 중요성

웹훅 이벤트는 여러 번 전송될 수 있으므로 핸들러가 idempotent를 유지해야 합니다.

구독 상태

상태는 구독의 현재 상태를 추적하는 데 사용됩니다.

상태설명
trial구독이 시험 기간에 있습니다.
active구독이 결제 완료되었고 정상 상태입니다.
canceled구독이 갱신되지 않을 것입니다. effective_until까지 활성 상태로 유지되며, 그 후 expired로 전환됩니다.
expired구독이 더 이상 활성 상태가 아닙니다.
전방 호환성

향후 새 구독 상태가 추가될 수 있습니다.

통합이 앞으로도 호환되도록 하려면, 혜택을 부여하거나 회수하는 데 구독 상태만 단독으로 의존하지 마세요. 구독 액세스를 활성화 및 비활성화하기 위한 단일 진실 공급원(source of truth)으로는 항상 event_type 및 effective_until에 의존하세요.

코드에서 status를 엄격한 enum으로 모델링하지 마세요 — 새 값이 도입될 때 깨지는 것을 방지하기 위해 문자열로 취급하세요.

공통 시나리오

다음 예는 일반적인 구독 흐름 및 각 단계에서 발생하는 이벤트를 보여줍니다:

트라이얼 → 결제 완료

  1. subscription.activated status=trial → 접근 권한 부여
  2. subscription.updated status=active → 시험이 결제로 전환됨 (첫 번째 성공적인 결제), effective_until 확장

정기 결제

  1. subscription.renewed status=active → 접근 확장 (effective_until 업데이트)
  2. (선택 사항) 각 성공적인 갱신 시 보상을 제공하십시오 (적용되는 경우).

취소

  1. subscription.updated status=canceled → effective_until까지 접근 유지
  2. subscription.deactivated → 접근 취소

만료

  1. subscription.deactivated 상태=expired → 접근 취소
  2. (선택 사항) 웹훅을 받지 못한 경우 now >= effective_until일 때 접근을 취소하십시오.

요구 사항

Aghanim의 구독 웹훅을 사용하려면 웹훅 서버를 다음과 같이 구성해야 합니다:

  • POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
  • Aghanim이 생성하고 서명한 이벤트를 수신합니다.
  • 중복 웹훅 처리를 방지하기 위해 웹훅 페이로드에 포함된 idempotency_key를 처리합니다.
  • 구독 이벤트가 성공적으로 처리된 경우 2xx 상태 코드로 응답하고, 오류가 발생하면 4xx 또는 5xx로 응답합니다.

구성

  1. 구독 웹훅 처리를 위한 함수를 개발합니다.
  2. 엔드포인트를 사용 가능하게 설정하세요.
  3. Aghanim 계정에서 → 게임 → 웹훅 → 새 웹훅에서 처리하고자 하는 구독 이벤트 유형을 선택하여 엔드포인트를 등록하세요.

대안으로, 웹후크 생성 API 방법을 사용하여 Aghanim 내에서 엔드포인트를 등록할 수 있습니다.

요청 스키마

아래는 예시입니다 subscription.activated 웹훅 요청:

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "subscription.activated",
  "event_data": {
    "id": "sub_kMnoPqRsTuV",
    "sku": "battle_pass",
    "name": "Battle Pass",
    "nested_items": [
      {
        "id": "itm_zzzzzzz",
        "name": "독점 스킨",
        "description": "한정판 구독자 스킨",
        "sku": "exclusive_skin_001",
        "quantity": 1,
        "type": "item"
      }
    ],
    "order_id": "ord_eCacpFwavzi",
    "user_id": "usr_eymySUreClx",
    "player_id": "2D2R-OP3C",
    "amount": 999,
    "amount_decimal": 9.99,
    "currency": "USD",
    "payment_method": "cards",
    "status": "active",
    "due_at": 1706745600,
    "created_at": 1704067200,
    "plan": {
      "key": "battle_pass_monthly",
      "name": "Battle Pass Monthly",
      "amount": 999,
      "amount_decimal": 9.99,
      "currency": "USD",
      "offer": {
        "key": "season_launch",
        "name": "시즌 시작 보너스",
        "description": "시즌 시작 특별 할인",
        "discount_percent": 20,
        "grace_extension": 3,
        "trial_extension": 7
      },
      "cycle_period": 30,
      "grace_period": 3,
      "trial_period": 7,
      "nested_items": [
        {
          "id": "itm_xxxxxxx",
          "name": "500 보너스 골드",
          "description": "월별 구독자 보너스 골드",
          "sku": "bonus_gold_500",
          "quantity": 1,
          "type": "item"
        },
        {
          "id": "itm_yyyyyyy",
          "name": "XP 부스트",
          "description": "구독 기간 동안 활성화된 25% XP 부스트",
          "sku": "xp_boost_25",
          "quantity": 1,
          "type": "item"
        }
      ]
    },
    "effective_until": 1705276800,
    "trial_due_at": 1705276800,
    "paid_due_at": 1704067200,
    "updated_at": 1704067200,
    "metadata": {
      "tier": "premium",
      "referral_code": "SUMMER2024"
    }
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "subscription.activated",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

Key유형설명
event_idstringAghanim에 의해 생성된 고유 이벤트 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
event_typestring이벤트의 유형, subscription.activated 이럴 경우.
event_timenumber유닉스 에포크 시간으로 된 이벤트 날짜.
event_dataEventData이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_keystring웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다.
request_idstring|null이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandboxboolean이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstringAghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
contextEventContext|null이벤트에 대한 컨텍스트 정보.

EventContext 스키마

Key유형설명
orderOrderContext|null해당되는 경우 이벤트와 관련된 주문 정보입니다.
playerPlayerContext|null플레이어 정보를 추가하려면 웹훅 설정에서 "플레이어 컨텍스트 추가"를 활성화하세요.

The EventData schema

idstringUnique identifier for this subscription instance. Use this ID to track and manage the subscription throughout its lifecycle.
Key유형설명
skustringSubscription unique SKU.
namestringSubscription display name.
nested_itemsNestedItem[]Items included in this subscription.
order_idstringOrder ID where the subscription was originally activated. Use this to correlate with order webhooks.
user_idstringAghanim 시스템에서 게임 허브 유저 ID.
player_idstring고유한 플레이어 인증에 선택된 플레이어 ID.
amountnumberSubscription amount in 소수 통화 단위.
amount_decimalnumberSubscription amount in major currency units.
currencystringSubscription 통화.
payment_methodstringPayment method used (cards, apple_pay, google_pay, paypal, etc.).
statusstringSubscription status. See Subscription statuses above.
due_atnumberNext payment due date in Unix epoch time (seconds). For trial subscriptions, this is when the first charge will occur.
created_atnumberSubscription creation date in Unix epoch time (seconds).
planPlanPlan associated with the subscription.
effective_untilnumberThe date until which the subscription is effective in Unix epoch time (seconds). This is the higher value between trial_due_at and paid_due_at, representing when the subscription benefits should remain accessible.
trial_due_atnumber|nullTrial end date in Unix epoch time (seconds). Null if subscription has no trial.
paid_due_atnumber|nullDate through which the subscription is paid (paid-through date) in Unix epoch time (seconds). After this date, the subscription must be renewed or it will become expired. Null during trial or before first payment.
updated_atnumber|nullSubscription last update date in Unix epoch time (seconds). Null if the subscription has not been updated.
metadataobject|nullCustom key-value pairs attached to the subscription. Null if no metadata is set.

The Plan schema

Key유형설명
keystringPlan unique key within subscription.
namestringPlan display name.
amountnumberPlan amount in 소수 통화 단위.
amount_decimalnumberPlan amount in major currency units.
currencystringPlan 통화.
offerOffer|nullOffer applied to the plan. Null if no offer is applied.
cycle_periodnumber|nullRecurring billing interval in days (e.g., 30 for monthly, 365 for yearly).
grace_periodnumber|nullNumber of days after a failed payment during which the subscription remains active while retry attempts are made. Null if no grace period is configured.
trial_periodnumber|nullTrial period duration in days. Null if plan has no trial.
nested_itemsNestedItem[]Items included in this plan.

The Offer schema

Key유형설명
keystringOffer unique key.
namestring|nullOffer display name.
descriptionstring|nullOffer description.
discount_percentnumber|nullDiscount percentage.
grace_extensionnumber|nullGrace period extension in days.
trial_extensionnumber|nullTrial period extension in days.

NestedItem 스키마

Key유형설명
idstringAghanim에 의해 생성된 아이템 ID.
namestring아이템 이름.
descriptionstring|null아이템 설명.
skustring게임과 Aghanim 측 모두에서 일치하는 아이템 SKU.
quantitynumber아이템 수량.
fallback_itemItem|null주 아이템을 플레이어에게 제공할 수 없을 경우 백업으로 제공할 수 있는 아이템입니다.
metadataobject|nullCustom key-value pairs for the item to support additional logic on your end.

도움이 필요하세요?
통합팀에 문의하십시오 [email protected]

On this page