Skip to main content

Analytics Webhooks

Aghanim's analytics webhooks notify your game of frontend-only player interactions on the game hub and checkout page.

These webhooks are organized into two namespaces based on where the interaction occurs:

  • analytics.hub.* — Events from the game hub
  • analytics.checkout.* — Events from the checkout page

This webhook is activated through the Analytics events event, selectable in Game → Webhooks.

Requirements

To use the analytics events 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 if the event was processed successfully, and 4xx or 5xx for denial or errors.

Configuration

  1. Develop a function for the analytics.* webhook processing.
  2. Make your endpoint available.
  3. Register your endpoint within Aghanim account → Game → Webhooks → Add webhook by choosing the analytics events event type.

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

Webhook Batch Export

Analytics events can generate high volumes of traffic. Consider enabling batch mode to receive events as downloadable JSONL files instead of individual HTTP requests.

Trigger values

ValueEmitsDescription
hub.interactanalytics.hub.*Player interacted with the game hub (sign-up, login, buy click, etc.).
checkout.interactanalytics.checkout.*Player interacted with the checkout page (pageview, form submit, etc.).
testAny analytics eventWhen using the "Send test event" in the Dashboard.

See the full events and triggers matrix for how analytics events relate to other event types.

Request schema

Below is an example of an analytics.hub.buy_click 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": "analytics.hub.buy_click",
  "event_data": {
    "name": "hub.buy_click",
    "action": "event",
    "label": "",
    "user_id": "usr_eymySUreClx",
    "player_id": "2D2R-OP3C",
    "order_id": null,
    "device": {
      "type": "mobile",
      "model": "iPhone"
    },
    "country": "US",
    "referrer": "https://manabuff.com/store",
    "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "tz_offset": 5
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.interact",
  "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, analytics.hub.buy_click in this case.
event_timenumberEvent date in Unix epoch time.
event_dataEventDataContains the event-specific data, with possible keys for inherited objects.
idempotency_keystring|nullEnsures webhook actions are executed only once, even if retried. Can be null depending on event type.
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.
contextobject|nullContextual information about the event.

The EventData schema

FieldTypeDescription
namestringThe analytics event name (e.g. hub.sign_up, hub.buy_click, checkout.submit_payment_form)
actionstringInteraction action (event, click, submit, open, close, error)
labelstring|nullEvent-specific context (e.g. login method, payment method name). Can be null
user_idstringAghanim user ID
player_idstringThe player ID in your game
order_idstring|nullAssociated order ID, if applicable
deviceDeviceDevice information
countrystringPlayer's country code (e.g. US, DE)
referrerstringTraffic source URL. Can be empty
useragentstringBrowser user agent string
tz_offsetnumberPlayer's timezone offset in hours from UTC

The Device schema

FieldTypeDescription
typestringmobile or desktop
modelstringDevice model when available (e.g. iPhone, Android). Can be empty

Game hub events

Events triggered by player interactions on the game hub.

EventDescription
analytics.hub.buy_clickPlayer initiated a purchase
analytics.hub.free_item_claimedPlayer claimed a free item
analytics.hub.loginPlayer logged in to the hub
analytics.hub.sign_upPlayer registered on the hub

Checkout events

Events triggered by player interactions on the checkout page.

EventDescription
analytics.checkout.back_gamePlayer navigated back to the game
analytics.checkout.back_storePlayer navigated back to the store
analytics.checkout.pageexitPlayer exited the checkout page
analytics.checkout.pagehidePlayer navigated away from the checkout page
analytics.checkout.pageshowPlayer returned to the checkout page
analytics.checkout.pageviewPlayer opened the checkout page
analytics.checkout.submit_payment_formPlayer submitted the payment form

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

On this page