Skip to main content

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

Below is an example of an subscription.activated webhook request:

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"
}

The Event schema

KeyTypeDescription
event_idstringUnique Event ID generated by Aghanim.
game_idstringYour game ID in the Aghanim system.
event_typestringThe type of the event, subscription.activated in this case.
event_timenumberEvent date in Unix epoch time.
event_dataEventDataContains the event-specific data, with possible keys for inherited objects.
idempotency_keystringEnsures webhook actions are executed only once, even if retried.
request_idstring|nullIf the event was triggered by an API request, the request ID is included.
sandboxbooleanIndicates whether the event was sent from the sandbox game environment.
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstringThe transaction ID generated by Aghanim. This ID may be the same for multiple events emitted within the same transaction.
contextEventContext|nullContextual information about the event.

The EventContext schema

KeyTypeDescription
orderOrderContext|nullOrder information associated with the event if applicable.
playerPlayerContext|null(Optional) Player information. To add this, enable "Add player context" in the webhook settings.

The EventData schema

idstringUnique identifier for this subscription instance. Use this ID to track and manage the subscription throughout its lifecycle.
KeyTypeDescription
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_idstringGame Hub user ID in the Aghanim system.
player_idstringThe unique Player ID chosen for player authentication.
amountnumberSubscription amount in minor currency units.
amount_decimalnumberSubscription amount in major currency units.
currencystringSubscription currency.
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

KeyTypeDescription
keystringPlan unique key within subscription.
namestringPlan display name.
amountnumberPlan amount in minor currency units.
amount_decimalnumberPlan amount in major currency units.
currencystringPlan currency.
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

KeyTypeDescription
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.

The NestedItem schema

KeyTypeDescription
idstringItem ID generated by Aghanim.
namestringItem name.
descriptionstring|nullItem description.
skustringItem SKU matching on both the game and Aghanim sides.
quantitynumberItem quantity.
typestringThe type of item. Possible values: item, bundle.
nested_itemsNestedItem[]|nullAn array of items included in the bundle.

Need help?
Contact our integration team at integration@aghanim.com

On this page