Store Get Webhook

The store.get webhook retrieves a list of items available for a player in the Game Hub store. This is useful for displaying the store content based on game logic.

This webhook is triggered in the following cases:

A player logs in to the game hub.
A player opens the store.
A player makes a purchase.

Requirements

To use the store.get webhook 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.
Respond with 2xx status codes to signal successful processing, and 4xx or 5xx for denial or errors.

Configuration

Develop a function for the store.get webhook processing.
Make your endpoint available.
Register your endpoint within Aghanim account → Game → Webhooks → New Webhook by choosing the store.get event type.

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

Request schema

Below is an example of an store.get webhook request:

HTTP
cURL

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": "store.get",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "is_anonymous": false,
    "placement_keys": null,
    "category_slugs": null,
    "current_page_path": "/store",
    "locale": "en"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.store.open",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}
            

curl "https://your-webhook-endpoint.com/your/webhook/uri" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "User-Agent: Aghanim/0.1.0" \
    -H "X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812" \
    -H "X-Aghanim-Signature-Timestamp: 1725548450" \
    -d '{
      "event_type": "store.get",
      "event_data": {
        "player_id": "2D2R-OP3C",
        "is_anonymous": false,
        "placement_keys": null,
        "category_slugs": null,
        "current_page_path": "/store",
        "locale": "en"
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "hub.store.open",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

The Event schema

Key	Type	Description
`event_id`	`string`	Unique Event ID generated by Aghanim.
`game_id`	`string`	Your game ID in the Aghanim system.
`event_type`	`string`	The type of the event, `store.get` in this case.
`event_time`	`number`	Event date in Unix epoch time.
`event_data`	`EventData`	Contains the event-specific data, with possible keys for inherited objects.
`idempotency_key`	`string`	Ensures webhook actions are executed only once, even if retried.
`request_id`	`string\|null`	If the event was triggered by an API request, the request ID is included.
`sandbox`	`boolean`	Indicates whether the event was sent from the sandbox game environment.
`trigger`	`string\|null`	The trigger that caused the event to be sent.
`transaction_id`	`string`	The transaction ID generated by Aghanim. This ID may be the same for multiple events emitted within the same transaction.
`context`	`EventContext\|null`	Contextual information about the event.

The EventContext schema

Key	Type	Description
`order`	`OrderContext\|null`	Order information associated with the event if applicable.
`player`	`PlayerContext\|null`	(Optional) Player information. To add this, enable "Add player context" in the webhook settings.

The EventData schema

Key	Type	Description
`player_id`	`string`	The unique Player ID chosen for player authentication.
`is_anonymous`	`boolean`	Indicates whether the current user is unauthenticated (anonymous).
`placement_keys`	`string[]\|null`	List of placement keys from where `store.get` was requested.
`category_slugs`	`string[]\|null`	List of category slugs from where `store.get` was requested.
`current_page_path`	`string\|null`	Path of the currently opened page, relative to the game hub root (for example, `/store/offers`).
`locale`	`string`	The current player's locale code (ISO 639-1). Find the full list of possible locales in Locales.

The Trigger values

Value	Description
`hub.store.open`	When the store is opened.
`hub.login`	When the player opens the game hub.
`hub.purchase`	When the player clicks the buy button in the store to verify that the item is still available for the player.
`order.captured`	Just before payment processing begins, to verify that the item is still available for the player.
`test`	When using the "Send test event" in the Dashboard.

Response schema

Upon a successful response, your server is expected to return a status code in the 2xx range and the following JSON payload:

Key	Type	Description	Required?
`items`	`[Item\|BundleItem]`	An array of items available for the player in the store.	No
`rolling_offers`	`RollingOffer[]`	An array of rolling offers available for the player	No

The Item schema

Key	Type	Description	Required?
`sku`	`string`	Item SKU matching on both the game and Aghanim sides.	Yes
`start_at`	`number`	The unix-timestamp when the item becomes available to the player.	No
`end_at`	`number`	The unix-timestamp when the item expires and is no longer available to the player.	No
`max_purchases`	`number`	The maximum number of purchases allowed for the item.	No

The BundleItem schema

Key	Type	Description	Required?
`sku`	`string`	The unique SKU identifier for the dynamic bundle item	Yes
`price`	`number`	The price in USD in cents	Yes
`name`	`string`	The name of the bundle item	Yes
`nested_items`	`NestedItem[]`	An array of items included in the bundle.	Yes
`description`	`string`	The description of the bundle item	No
`image_url`	`string`	The image URL of the bundle item	No
`image_url_featured`	`string`	The image URL for the bundle item when displayed as a featured item. Applies only if the item is featured.	No
`featured_card_background_image_url`	`string`	The background image URL for the bundle item card when displayed as a featured item. Applies only if the item is featured.	No
`category_slugs`	`string[]`	Array of category slugs to determine the placement of the bundle item	No
`start_at`	`number`	The unix-timestamp when the item becomes available to the player.	No
`end_at`	`number`	The unix-timestamp when the item expires and is no longer available to the player.	No
`max_purchases`	`number`	The maximum number of purchases allowed for the item. Once the limit is reached, the item disappears from the store	No
`price_template_id`	`string`	The ID of the price template that will be used for pricing in different countries.	No
`custom_badge`	`string`	Custom badge text of the bundle	No
`bonus_items`	`WebhookItemBonus[]`	An array of bonus items included in the bundle	No
`bonus_badge`	`string`	Badge text about bonus items	No
`bonus_percent`	`number`	Bonus percent applied for first stackable item in nested_items	No
`bonus_fixed`	`number`	Fixed bonus value applied to the first stackable item in nested_items. If set, bonus_percent is ignored.	No
`metadata`	`object`	The metadata object structured as key-value pairs to store additional information about the item.	No
`view_option`	`ItemViewOption`	Controls the store appearance of the item. Allowed values: `default`, `in_title`	No
`card_type`	`StoreCardType`	The type of the card for the item, used for displaying in the store: `default`, `featured`	No
`free_claims`	`FreeClaims`	Settings to make the item claimable for free instead of being purchased.	No

The NestedItem schema

Key	Type	Description	Required?
`sku`	`string`	Item SKU matching on both the game and Aghanim sides.	Yes
`quantity`	`number`	The quantity of the nested item, relevant for stackable items	No
`is_featured`	`boolean`	Define if item is featured in the bundle list	No
`metadata`	`object`	The metadata object structured as key-value pairs to store additional information about the item.	No

The WebhookItemBonus schema

Key	Type	Description	Required?
`sku`	`string`	Item SKU matching on both the game and Aghanim sides.	Yes
`quantity`	`number`	The quantity of the bonus item, relevant for stackable items	No

The FreeClaims schema

Key	Type	Description	Required?
`enabled`	`boolean`	Indicates whether the item can be claimed for free instead of being purchased.	Yes
`max_claims`	`number`	The maximum number of times an item can be claimed within the specified period.	Yes
`period`	`Period`	Period window used to reset `max_claims`. If omitted, the limit will not reset after the maximum number of claims is reached.	No
`exceeded_claims_behavior`	`ExceededClaimsBehavior`	Defines behavior after reaching the maximum number of claims. Allowed values: `hide` – removes the item from the store; `disable_with_timer` – keeps it visible but disabled with a countdown until the next reset. If the `period` is omitted, the countdown is not shown and the item remains disabled.	No

The Period schema

Key	Type	Description	Required?
`unit`	`PeriodType`	The type of period used for the claim limit. Possible values: `month`, `week`, `day`, `hour`.	Yes
`duration`	`number`	The duration of the period, measured in the units specified by `unit` (for example, duration: 2 with unit: day, represents a two-day period).	Yes

The RollingOffer schema

Key	Type	Description	Required?
`key`	`string`	Unique offer key used to determine whether the item has been purchased or claimed.	Yes
`placement_key`	`string`	Key of the block in game hub, where the rolling offer will be displayed.	Yes
`name`	`string`	Title of the rolling offer.	Yes
`description`	`string`	Description of the rolling offer.	Yes
`rolling_items`	`RollingItem[]`	List of items included in the rolling offer.	Yes
`background_image_url`	`string`	URL of the background image.	No
`background_size`	`string`	Size of the background image. Possible values: `contain`, `repeat`, `cover`.	No
`expire_at`	`number`	Expiration time of the offer as a Unix timestamp. The timer in the offer block counts down to this moment and the offer becomes hidden when it’s reached.	No

The RollingItem schema

Key	Type	Description	Required?
`sku`	`string`	The unique SKU identifier for the dynamic bundle item.	Yes
`quantity`	`number`	The quantity of the item, relevant for stackable items.	No
`is_free_item`	`boolean`	Indicates whether the item can be claimed for free instead of being purchased.	No

Example of a successful response

{
  "items": [
    {
      "sku": "crystals"
    },
    {
      "sku": "shield",
      "start_at": 1630000000,
      "end_at": 1635000000
    },
    {
      "sku": "fly_bundle",
      "price": 2000,
      "name": "Fly Bundle",
      "description": "Fly Bundle Description",
      "image_url": "https://example.com/fly-bundle.png",
      "image_url_featured": "https://example.com/fly-bundle-featured.png",
      "featured_card_background_image_url": "https://example.com/fly-bundle-featured-background.png",
      "nested_items": [
        {
          "sku": "nested_item_sku_1"
        },
        {
          "sku": "nested_item_sku_2",
          "quantity": 200
        }
      ],
      "category_slugs": [
        "category_slug_1"
      ]
    },
    {
        "sku": "free-fly-bundle-with-timer",
        "name": "Fly Bundle",
        "description": "Bundle with fly and sword",
        "background_image_url": "https://example.com/background.jpg",
        "category_slugs": ["first"],
        "nested_items": [
            {"sku": "diamond-002", "quantity": 2},
            {"sku": "sword-thb"},
        ],
        "free_claims": {
            "enabled": True,
            "max_claims": 1,
            "period": {"unit": "day", "duration": 1},
            "exceeded_claims_behavior": "disable_with_timer",
        }
    }
  ], 
  "rolling_offers": [
    {
      "key": "rolling_offer_1",
      "placement_key": "place1",
      "name": "Dynamic Special Offer",
      "description": "Limited time offer",
      "rolling_items": [
        {
          "sku": "coins",
          "quantity": 256,
          "is_free_item": false
        },
        {
          "sku": "gold",
          "quantity": 999,
          "is_free_item": true
        }
      ],
      "background_image_url": "https://static-platform.aghanim.com/image.webp",
      "background_size": "cover",
      "expire_at": 1762964336
    }
}

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