Item Remove Webhook

Aghanim offers a centralized webhook that alerts your game to remove items from a player's account.

This webhook is triggered in the following cases:

• A bank or payment system reverses a player's transaction on the game hub
• A transaction refund is requested via the Transactions section of the Aghanim Dashboard

Each event includes a reason field with the justification for item removal.

Requirements

To use the item.remove 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.
• Remove items of the reversed or refunded order from a player's account accordingly or perform other required actions.
• Respond with 2xx status codes to signal successful processing, and 4xx or 5xx for denial or errors.

Configuration

Below are function templates for an endpoint that processes Aghanim webhooks, alerting your game to remove items:

• Python
• Ruby
• Node.js
• Go

import fastapi, hashlib, hmac, json, typing 

app = fastapi.FastAPI()

@app.post("/webhook")
async def webhook(request: fastapi.Request) -> dict[str, typing.Any]:
    secret_key = "<YOUR_S2S_KEY>"  # Replace with your actual webhook secret key

    raw_payload = await request.body()
    payload = raw_payload.decode()
    timestamp = request.headers["x-aghanim-signature-timestamp"]
    received_signature = request.headers["x-aghanim-signature"]

    if not verify_signature(secret_key, payload, timestamp, received_signature):
        raise fastapi.HTTPException(status_code=403, detail="Invalid signature")

    data = json.loads(payload)
    event_type = data["event_type"]
    event_data = data["event_data"]

    if event_type == "item.remove":
        remove_item(event_data)
        return {"status": "ok"}

    raise fastapi.HTTPException(status_code=400, detail="Unknown event type")

def verify_signature(secret_key: str, payload: str, timestamp: str, received_signature: str) -> bool:
    signature_data = f"{timestamp}.{payload}"
    computed_hash = hmac.new(secret_key.encode(), signature_data.encode(), hashlib.sha256)
    computed_signature = computed_hash.hexdigest()
    return hmac.compare_digest(computed_signature, received_signature)

def remove_item(event_data: dict[str, typing.Any]) -> None:
    # Placeholder logic for processing the event and removing item.
    # In a real application, this function would interact with your database or inventory system.
    player_id = event_data["player_id"]
    for item in event_data["items"]:
      sku = event_data["sku"]
      print(f"Item {sku} have been removed from player's {player_id} account.")

require 'sinatra'
require 'json'
require 'openssl'

post '/webhook' do
  secret_key = "<YOUR_S2S_KEY>"  # Replace with your actual webhook secret key

  payload = request.body.read
  timestamp = request.env["HTTP_X_AGHANIM_SIGNATURE_TIMESTAMP"]
  received_signature = request.env["HTTP_X_AGHANIM_SIGNATURE"]

  unless verify_signature(secret_key, payload, timestamp, received_signature)
    halt 403, "Invalid signature"
  end

  data = JSON.parse(payload)
  event_type = data["event_type"]
  event_data = data["event_data"]

  if event_type == "item.remove"
    remove_item(event_data)
    return { status: "ok" }.to_json
  end

  halt 400, "Unknown event type"
end

def verify_signature(secret_key, payload, timestamp, received_signature)
  signature_data = "#{timestamp}.#{payload}"
  computed_signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, signature_data)
  OpenSSL.secure_compare(computed_signature, received_signature)
end

def remove_item(event_data)
  # Placeholder logic for processing the event and removing item.
  # In a real application, this function would interact with your database or inventory system.
  player_id = event_data["player_id"]
  for item in event_data["items"] do
    sku = item["sku"]
    puts "Item #{sku} has been removed from player's #{player_id} account."
  end
end

const express = require('express');
const crypto = require('crypto');

const app = express();

app.post('/webhook', express.raw({ type: "*/*" }), async (req, res) => {
  const secretKey = '<YOUR_S2S_KEY>'; // Replace with your actual webhook secret key

  const rawPayload = req.body;
  const timestamp = req.headers['x-aghanim-signature-timestamp'];
  const receivedSignature = req.headers['x-aghanim-signature'];

  if (!verifySignature(secretKey, rawPayload, timestamp, receivedSignature)) {
    return res.status(403).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);
  const { event_type, event_data } = payload;

  if (event_type === 'item.remove') {
    removeItem(event_data);
    return res.json({ status: 'ok' });
  }

  return res.status(400).send('Unknown event type');
});

function verifySignature(secretKey, payload, timestamp, receivedSignature) {
  const signatureData = `${timestamp}.${payload}`;
  const computedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(signatureData)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(receivedSignature));
}

function removeItem(event_data) {
  // Placeholder logic for processing the event and removing item.
  // In a real application, this function would interact with your database or inventory system.  
  const playerId = event_data.player_id;
  for (const item of event_data.items) {
    const sku = item.sku;
    console.log(`Item ${item.sku} has been removed from player's ${playerId} account.`);
 }
}

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  secretKey := "<YOUR_S2S_KEY>"  // Replace with your actual webhook secret key

  rawPayload, _ := ioutil.ReadAll(r.Body)
  payload := string(rawPayload)
  timestamp := r.Header.Get("X-Aghanim-Signature-Timestamp")
  receivedSignature := r.Header.Get("X-Aghanim-Signature")

  if !verifySignature(secretKey, payload, timestamp, receivedSignature) {
    http.Error(w, "Invalid signature", http.StatusForbidden)
    return
  }

  var data map[string]interface{}
  if err := json.Unmarshal(rawPayload, &data); err != nil {
    http.Error(w, "Invalid payload", http.StatusBadRequest)
    return
  }

  eventType := data["event_type"].(string)
  eventData := data["event_data"].(map[string]interface{})

  if eventType == "item.remove" {
    removeItem(eventData)
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
    return
  }

  http.Error(w, "Unknown event type", http.StatusBadRequest)
}

func verifySignature(secretKey, payload, timestamp, receivedSignature string) bool {
  signatureData := fmt.Sprintf("%s.%s", timestamp, payload)
  mac := hmac.New(sha256.New, []byte(secretKey))
  mac.Write([]byte(signatureData))
  computedSignature := hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(computedSignature), []byte(receivedSignature))
}

func removeItem(eventData map[string]interface{}) {
  // Placeholder logic for processing the event and removing item.
  // In a real application, this function would interact with your database or inventory system.
  playerID := eventData["player_id"].(string)
  items := eventData["items"].([]interface{})
  for _, item := range items {
    itemMap := item.(map[string]interface{})
    sku := itemMap["sku"].(string)
    fmt.Printf("Item %s has been removed from player's %s account.\\n", sku, playerID)
  }
}

Once your function is ready:

1. Make your endpoint available.
2. Register your endpoint within Aghanim account → Game → Webhooks → New Webhook by choosing the corresponding event type.

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

Request schema

Below is an example of an item.remove webhook request:

HTTP

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": "item.remove",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "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
      }
    ],
    "reason": "Order refunded ord_eCacAulggpY"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "order.refunded",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": {
    "order": {
      "id": "ord_eCacAulggpY",
      "amount": 9499,
      "country": "US",
      "currency": "USD",
      "revenue_usd": 9499,
      "fees": {
        "payment_system_fee_usd": 2.85,
        "aghanim_fee_usd": 14.25,
        "taxes_usd": 7.65
      },
      "receipt_number": "1234567890",
      "status": "refunded",
      "created_at": 1725548450,
      "paid_at": 1725548460,
      "creator": null
    }
  },
  "game_id": "gm_exTAyxPsVwh"
}
            

cURL

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": "item.remove",
      "event_data": {
        "player_id": "2D2R-OP3C",
        "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
          }
        ],
        "reason": "Order refunded ord_eCacAulggpY"
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "order.refunded",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": {
        "order": {
          "id": "ord_eCacAulggpY",
          "amount": 9499,
          "country": "US",
          "currency": "USD",
          "revenue_usd": 9499,
          "fees": {
            "payment_system_fee_usd": 2.85,
            "aghanim_fee_usd": 14.25,
            "taxes_usd": 7.65
          },
          "receipt_number": "1234567890",
          "status": "refunded",
          "created_at": 1725548450,
          "paid_at": 1725548460,
          "creator": 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, item.remove 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.
items	Item[]	An array of items to be removed from the player's account.
reason	string	The human-readable reason that triggered the webhook. Example: Order refunded ord_eCacAulggpY.
item_id	string	[Deprecated] Item ID generated by Aghanim.
sku	string	[Deprecated] Item SKU matching on both the game and Aghanim sides.

The Trigger values

Value	Description
order.refunded	When a payment is refunded.
order.canceled	When a chargeback occurs.
test	When using the "Send test event" in the Dashboard.

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|null	Item price in minor currency units. If the item is free, this field is null.
price_decimal	number|null	Item price in decimal units. If the item is free, this field is null.
currency	string|null	Item price currency. If the item is free, this field is null.
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 OrderContext schema

Key	Type	Description
id	string	Unique Order ID generated by Aghanim.
receipt_number	string	Receipt number shown to the player in their receipt.
amount	number	Order amount in local currency, in minor currency units.
amount_before_discount	number	Order amount before discount in local currency, in minor currency units.
payment_amount	number	Final amount charged to the customer in local currency, including taxes, in minor currency units.
currency	string	Three-letter currency code (ISO 4217) of the order.
payment_method	string	The payment method used, for example card, apple_pay, google_pay, paypal.
country	string	Two-letter country code (ISO 3166-1 alpha-2) of the payment method country.
payment_amount_usd	number	The payment amount converted to USD (e.g., 112.50 for $112.50) using estimated foreign exchange rates. The final value is confirmed after reconciliation with payment providers, typically by the 10th of the following month.
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.
fees	Fees|null	Information about taxes and fees. The final values are determined after reconciliation with payment providers, typically by the 10th of the following month.
status	string	Order status. Can be: created, captured, paid, canceled, refunded, refund_requested.
sales_channel	string	Indicates the sales channel. Can be: game_hub, checkout, android_sdk, checkout_link.
eligible_for_reward_points	number|null	The number of reward points the order is eligible for.
eligible_for_loyalty_points	number|null	The number of loyalty points the order is eligible for.
created_at	number	Order creation date in Unix epoch time.
paid_at	number|null	Order payment date in Unix epoch time.
creator	Creator|null	Information about creator associated with the order.
metadata	object|null	The metadata object structured as key-value pairs to store additional information about the order.

The Fees schema

Key	Type	Description
payment_system_fee_usd	number|null	Payment processing fee in USD cents.
aghanim_fee_usd	number|null	Aghanim platform fee in USD cents.
taxes_usd	number|null	Taxes in USD cents.

The Creator schema

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

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.

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