Skip to main content

Webhook Overview

Aghanim leverages webhooks to alert your game to player-triggered events within the Aghanim-generated game hub, facilitating essential communication for 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"
}

Setting up webhook integration​

To manage events from Aghanim, you need to develop one or more functions. This choice depends on whether you prefer to process all events through a single endpoint or use multiple endpoints, with 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 ensures the delivery of webhook messages through a defined retry strategy that employs exponential backoff. If an initial delivery attempt fails, each subsequent attempt is made 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 instance, should a webhook message fail to deliver three times in succession, the successful delivery would take place 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:

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 concatenating the timestamp and raw payload using a dot (.). An example for Python:

    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 for Python:

    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 for Python:

    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()

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:

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