Webhook Overview

Aghanim uses webhooks to notify your game about player-triggered events within the Aghanim-generated game hub. These webhooks facilitate essential communication between Aghanim and your game. This guide outlines the workings and structure of Aghanim webhooks.

Webhooks are HTTP callbacks that Aghanim sends to the URLs you specify under Game → Webhooks → New Webhook in your Aghanim account. These requests are activated by specific events and carry a JSON payload with the relevant event data.

Schema

The Aghanim service sends HTTP POST requests to your webhook server, carrying a JSON payload structured with event data as follows:

{
  "event_type": "player.verify",
  "event_data": {"player_id": "2D2R-OP3C"},
  "event_time": 1725534306,
  "event_id": "whevt_eBZXsUEITGeDcILaZFUvPthxkr",
  "idempotency_key": null,
  "sandbox": false,
  "trigger": "hub.login",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "transaction_id": "whtx_eBZXsUEITGeDcILaZFUvPthxkr",
  "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 event. Possible values: player.verify, item.add, item.remove, order.paid, order.canceled, order.refunded, coupon.redeemed, ingame.push, ingame.popup.
event_time	number	Event date in Unix epoch time.
event_data	object	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	object|null	Contextual information about the event.

Setting up webhook integration

To manage events from Aghanim, you need to develop one or more functions. You can either process all events through a single endpoint or use multiple endpoints, each dedicated to specific events or different logic.

Requirements

Your function(s) should adhere to the following requirements and logic:

• 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.
• Appropriately process incoming requests, such as verifying players against your database to determine access to the game hub based on Player ID, or crediting purchased items to the player's account.
• Respond with 2xx status codes for access approval or once an item is credited, and 4xx or 5xx for denial or errors.

Registering your endpoint within Aghanim

1. Make your endpoint(s) available.
2. Register your endpoint(s) within Aghanim account → Game → Webhooks → New Webhook by choosing those events you want to be processed by this endpoint.
3. Copy a generated secret key and specify it in your webhook function for request signature validation.

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

Responding to events

In response to webhooks, Aghanim expects:

• 2xx (Success): This code indicates that the event has been successfully processed by a webhook function in accordance with its logic.
• 4xx or 5xx (Error): These codes trigger a retry sequence as per the retry schedule. If retries fail, Aghanim discontinues attempts, and the event is lost.

Retry schedule

Aghanim uses a retry strategy with exponential backoff to ensure webhook messages are delivered. If the initial delivery attempt fails, Aghanim will retry according to this sequence:

• Immediately after failure
• 5 seconds later
• 5 minutes later
• 30 minutes later
• 2 hours later
• 5 hours later
• 10 hours later
• Another 10 hours later
• If all retries fail, the message delivery is abandoned

For example, if a webhook message fails to deliver three times in a row, the successful delivery would occur approximately 35 minutes and 5 seconds after the initial attempt.

Idempotency

Aghanim includes an idempotency_key in the following webhooks to safely retry requests without triggering the same operation on the game's side twice:

• Item Add (item.add)
• Item Remove (item.remove)
• Order Paid (order.paid)
• Order Created (order.created)
• Order Refunded (order.refunded)
• Order Canceled (order.canceled)
• Coupon Redeemed (coupon.redeemed)
• Subscription (subscription.*)
• Fraud Reported (fraud.reported)

When processing these webhooks, rely on the uniqueness of the idempotency_key to ensure actions are executed only once:

• Perform the expected actions (e.g., granting an item) only when receiving a webhook with a unique idempotency_key for the first time.
• If a webhook with the same idempotency_key is received again, ignore it and respond with a 200 status code.

For example, if a connection error occurs and Aghanim retries sending the webhook, the idempotency_key will remain the same. This ensures the action on the game side is executed only once, allowing safe repetition of requests without unintended side effects.

Secure webhooks

Each request from Aghanim carries a unique, secret-key-based signature that allows you to verify the authenticity of the request. Webhook events include specific headers designed for security checks:

• X-Aghanim-Signature: the HMAC-SHA256 signature of the event payload.
• X-Aghanim-Signature-Timestamp: the exact time the event was triggered in Unix epoch time.

To verify the request's integrity:

1. Extract the raw payload and X-Aghanim-Signature-Timestamp header from the received event.

2. Form the signature data by concatenating the timestamp and the raw payload using a dot (.). Ensure that you use the raw bytes of the HTTPS request payload without any deserialization (to string or JSON parsing). An example in pseudocode:

   signature_data = timestamp + '.' + raw_payload

3. Retrieve the secret key specific to your webhook from your Aghanim account → Game → Webhooks → your webhook.

4. Generate an HMAC-SHA256 hash using the secret key. An example:

   computed_signature = hmac_sha256(secret_key, signature_data)

   info

   Use hexadecimal representation for the computed signature.

5. Compare the computed_signature against the X-Aghanim-Signature header from the received event. If they match, it confirms that the event is from a trusted source. An example in pseudocode:

   signature_data = timestamp + '.' + raw_payload
   computed_signature = hmac_sha256(secret_key, signature_data)
   
   # Compare the computed_signature and received_signature
   if computed_signature == received_signature:
     # Signature is valid
     process_webhook_event(raw_payload)
   else:
     # Signature is invalid
     ignore_webhook_event()

Using a firewall

The use of digital signatures guarantees the security of requests. However, if your security policy requires protecting endpoints with a firewall, this can also be configured. A list of IP addresses used to send webhook requests is available upon request. Please contact the team to obtain it.

Event types and function behavior

Aghanim provides the following types of events. Learn about the expected behavior of your function(s) in response to these events and what these events entail:

• Player Verify
• Item Add
• Item Remove
• Order Paid event
• Order Created event
• Order Canceled
• Refund
• Coupon Redeemed
• Mobile Push
• In-Game Popup
• Subscription
• Fraud Reported

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