In-Game Popup Webhook

Through Aghanim's LiveOps Builder, developers can trigger in-game popups in response to player actions or interactions within the Aghanim-generated game hub. Once the conditions outlined in a campaign are met, Aghanim dispatches a webhook to your game containing the popup content specified in the campaign.

Upon receiving this webhook, your game is expected to display the in-game popup to players. The design and development of the frontend part of the popup should align with your game's visual and interaction guidelines.

Requirements

To use the in-game popup 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.
Trigger the display of in-game popups using the received content, adhering to the game's design standards.
Respond with 2xx status codes upon successful receipt and processing of the webhook, and 4xx or 5xx for denial or errors.

Configuration

Develop a function for the ingame.popup webhook processing.
Make your endpoint available.
Register your endpoint within Aghanim account → Game → Webhooks → New Webhook by choosing the in-game popup event type.
Configure a liveops campaign that will trigger an in-game popup webhook.

Guide on configuring a campaign for an in-game popup

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

Request schema

Below is an example of an ingame.popup 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": "ingame.popup",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "title": "Hello!",
    "body": "How are you today? Claim your reward now!",
    "icon": null,
    "url": null
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "liveops.execute_action",
  "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": "ingame.popup",
      "event_data": {
        "player_id": "2D2R-OP3C",
        "title": "Hello!",
        "body": "How are you today? Claim your reward now!",
        "icon": null,
        "url": null
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": null,
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "liveops.execute_action",
      "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, `ingame.popup` 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\|null`	Ensures webhook actions are executed only once, even if retried. Can be `null` depending on event type.
`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 to display the popup to.
`title`	`string`	The popup title.
`body`	`string`	The popup body.
`icon`	`string\|null`	The popup icon URL.
`url`	`string\|null`	URL to open in the browser when a player clicks on the popup.

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