Order Paid Webhook

Aghanim's order paid webhook notifies your game of successfully completed payments on the game hub, providing detailed information about the transaction.

This webhook is activated through the Order paid event, selectable in Game → Webhooks.

warning

To credit in-game items to player accounts, use the item.add webhook. The order paid webhook is designed to provide detailed data when item.add is insufficient.

Requirements

To use the order paid 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.
Handle the idempotency_key included in the webhook payload to prevent processing duplicate webhooks.
Respond with 2xx status codes if a purchased item was credited successfully, and 4xx or 5xx for denial or errors.

Configuration

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

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

Request schema

Below is an example of an order.paid 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": "order.paid",
  "event_data": {
    "amount": 9499,
    "company_id": "com_exTAxmkZQCO",
    "country": "US",
    "created_at": 1725547595,
    "currency": "USD",
    "game_id": "gm_exTAyxPsVwh",
    "id": "ord_eCacpFwavzi",
    "revenue_usd": 9099.123,
    "fees": {
      "aghanim_fee_usd": 10.11,
      "payment_system_fee_usd": 15.123,
      "taxes_usd": 481.198933
    },
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "Crystals",
        "description": "Reign supreme over your rivals with this massive crystal treasure.",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD",
        "type": "item",
        "nested_items": null
      }
    ],
    "modified_at": 1725547657,
    "player_id": "2D2R-OP3C",
    "receipt_number": "2409051289614565",
    "status": "paid",
    "user_id": "usr_eymySUreClx",
    "metadata": null,
    "creator": null
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "checkout.purchase",
  "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": "order.paid",
      "event_data": {
        "amount": 9499,
        "company_id": "com_exTAxmkZQCO",
        "country": "US",
        "created_at": 1725547595,
        "currency": "USD",
        "game_id": "gm_exTAyxPsVwh",
        "id": "ord_eCacpFwavzi",
        "revenue_usd": 9099.123,
        "fees": {
          "aghanim_fee_usd": 10.11,
          "payment_system_fee_usd": 15.123,
          "taxes_usd": 481.198933
        },
        "items": [
          {
            "id": "itm_exTBZQmIlDz",
            "name": "Crystals",
            "description": "Reign supreme over your rivals with this massive crystal treasure.",
            "sku": "crystals",
            "quantity": 480000,
            "price": 9499,
            "price_decimal": 94.99,
            "currency": "USD",
            "type": "item",
            "nested_items": null
          }
        ],
        "modified_at": 1725547657,
        "player_id": "2D2R-OP3C",
        "receipt_number": "2409051289614565",
        "status": "paid",
        "user_id": "usr_eymySUreClx",
        "metadata": null,
        "creator": null
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "checkout.purchase",
      "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, `order.paid` 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
`id`	`string`	Order ID generated by Aghanim.
`company_id`	`string`	Your company ID in the Aghanim system.
`game_id`	`string`	Your game ID in the Aghanim system.
`user_id`	`string`	Game Hub user ID in the Aghanim system.
`player_id`	`string`	The unique Player ID chosen for player authentication.
`status`	`string`	Order status. Can be: `created`,`captured`,`paid`,`canceled`,`refunded`,`refund_requested`.
`amount`	`number`	Order amount in minor currency units.
`currency`	`string`	Order currency.
`country`	`string`	Payment method country.
`created_at`	`number`	Order creation date in Unix epoch time.
`modified_at`	`number`	Order modification date in Unix epoch time.
`items`	`Item[]`	Includes purchased item details.
`fees`	`Fees`	Information about taxes and fees.
`revenue_usd`	`number`	The expected net revenue, converted to USD cents using estimated foreign exchange rates and payment method fees. The final value is determined after reconciliation with payment providers, typically by the 10th of the following month.
`metadata`	`object\|null`	The metadata object structured as key-value pairs to store additional information about the order.
`creator`	`Creator\|null`	Information about creator associated with the order.

The Item schema

Key	Type	Description
`id`	`string`	Item ID generated by Aghanim.
`name`	`string`	Item name.
`description`	`string\|null`	Item description.
`sku`	`string`	Item SKU matching on both the game and Aghanim sides.
`quantity`	`number`	Item quantity.
`price`	`number`	Item price in minor currency units.
`price_decimal`	`number`	Item price in decimal units.
`currency`	`string`	Item price currency.
`type`	`string`	The type of item. Possible values: `item`, `bundle`.
`nested_items`	`NestedItem[]\|null`	An array of items included in the bundle.
`fallback_item`	`Item\|null`	The item that may be given as fallback if the main item can't be given to the player.

Item type bundle can contain several nested items inside.
You can handle the common sku of the bundle or handle each nested item individually.

The NestedItem schema

Key	Type	Description
`id`	`string`	Item ID generated by Aghanim.
`name`	`string`	Item name.
`description`	`string\|null`	Item description.
`sku`	`string`	Item SKU matching on both the game and Aghanim sides.
`quantity`	`number`	Item quantity.
`type`	`string`	The type of item. Possible values: `item`, `bundle`.
`nested_items`	`NestedItem[]\|null`	An array of items included in the bundle.

The PlayerContext schema

Key	Type	Description
`player_id`	`string\|null`	The unique Player ID chosen for player authentication.
`player`	`object\|null`	Player ID components when using Composite Authorization.
`attributes`	`Attributes`	Basic player attributes expected by Aghanim.
`custom_attributes`	`CustomAttributes`	Custom player attributes.

The Creator schema

Key	Type	Description
`name`	`string`	Name of the creator.
`payout_decimal_usd`	`number`	Creator payout amount in USD in major units.

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