跳至主要内容

Subscription Webhooks

Aghanim's subscription webhooks notify your game about subscription lifecycle events, allowing you to manage player access to subscription-based content and services.

Webhook events

Use these webhook events to grant, extend, or revoke subscription access.

EventWhen it firesWhat you should do
subscription.activatedSubscription becomes activeGrant subscription benefits to the player
subscription.updatedSubscription attributes change (status, plan, or billing dates)Sync your internal state with the updated subscription data
subscription.renewedRecurring payment succeedsExtend access by updating effective_until. Optionally, grant rewards on each successful renewal (if applicable)
subscription.deactivatedSubscription is deactivatedRevoke subscription benefits immediately
Idempotency matters

Webhook events may be delivered more than once, so handlers must be idempotent.

Subscription statuses

Statuses are used to track the current state of the subscription.

StatusDescription
trialThe subscription is in a trial period.
activeThe subscription is paid and in good standing.
canceledThe subscription will not renew. It remains active until effective_until, then transitions to expired.
expiredThe subscription is no longer active.
Forward compatibility

New subscription statuses may be added in the future.

To keep your integration forward-compatible, do not rely on subscription statuses alone to grant or revoke benefits. Always rely on event_type and effective_until as the source of truth for activating and deactivating subscription access.

Do not model status as a strict enum in your code — treat it as a string to avoid breaking when new values are introduced.

Common scenarios

The following examples show typical subscription flows and which events fire at each stage:

Trial → Paid

  1. subscription.activated status=trial → Grant access
  2. subscription.updated status=active → Trial converts to paid (first successful payment), extend effective_until

Recurring payment

  1. subscription.renewed status=active → Extend access (update effective_until)
  2. (Optional) Grant rewards on each successful renewal (if applicable)

Cancellation

  1. subscription.updated status=canceled → Access remains active until effective_until
  2. subscription.deactivated → Revoke access

Expiration

  1. subscription.deactivated status=expired → Revoke access
  2. (Optional) If you didn’t receive the webhook, revoke access when now >= effective_until

Requirements

To use subscription webhooks from Aghanim, you should have the webhook server configured as follows:

  • HTTPS endpoint, accepting POST webhook requests.
  • Listen for events, generated and signed by Aghanim.
  • Handle the idempotency_key included in the webhook payload to prevent processing duplicate webhooks.
  • Respond with 2xx status codes if the subscription event was processed successfully, and 4xx or 5xx for errors.

Configuration

  1. Develop a function for subscription webhook processing.
  2. Make your endpoint available.
  3. Register your endpoint within Aghanim account → Game → Webhooks → New Webhook by choosing the subscription event types you want to handle.

Alternatively, you can register your endpoint within Aghanim using the Create Webhook API method.

Request schema

下面是一个 subscription.activated Webhook 请求示例：

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": "Exclusive Skin",
        "description": "Limited edition subscriber skin",
        "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": "Season Launch Bonus",
        "description": "Special discount for season launch",
        "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 Bonus Gold",
          "description": "Monthly bonus gold for subscribers",
          "sku": "bonus_gold_500",
          "quantity": 1,
          "type": "item"
        },
        {
          "id": "itm_yyyyyyy",
          "name": "XP Boost",
          "description": "25% XP boost active during subscription",
          "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"
}

事件 Schema

键名类型描述
event_idstring阿哈利姆生成的唯一事件标识符。
game_idstring您的游戏在阿哈利姆中的唯一标识符。
event_typestring事件的类型， subscription.activated 在此情境下。
event_timenumber以 Unix 时间戳表示的事件发生日期。
event_dataEventData包含事件特定数据的字段，其中可能包含用于继承对象的各种键值。
idempotency_keystring即使出现重试情况，也能确保 Webhook 操作只执行一次。
request_idstring|null如果事件是通过 API 请求触发的，此字段将包含对应的请求 ID。
sandboxboolean标识事件是否来自沙盒测试环境的指示器。
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstring阿哈利姆生成的交易标识符。在同一交易过程中触发的多个事件可能共享相同的交易 ID。
contextEventContext|null事件的相关上下文信息。

EventContext Schema

键名类型描述
orderOrderContext|null与事件相关的订单信息（如果适用）。
playerPlayerContext|null（可选）玩家信息。如需启用，请在webhook设置中选择“添加玩家上下文”。

The EventData schema

idstringUnique identifier for this subscription instance. Use this ID to track and manage the subscription throughout its lifecycle.
键名类型描述
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_idstring用户在阿哈利姆游戏枢纽中的唯一标识符。
player_idstring唯一的 用于玩家身份验证的玩家标识符.
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

键名类型描述
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

键名类型描述
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 Schema

键名类型描述
idstring阿哈利姆生成的商品唯一标识符。
namestring商品名称。
descriptionstring|null商品描述。
skustring商品的 SKU 标识符，必须确保在游戏系统和阿哈利姆上保持一致。
quantitynumber商品数量。
typestring商品类型，可选值包括： item, bundle.
nested_itemsNestedItem[]|null礼包内包含的所有单独商品组成的数组。

需要技术支持？
联系我们的集成技术团队： integration@aghanim.com

On this page