Player Update Webhook

Aghanim's player update webhook notifies your game when a tracked player field changes on the Aghanim side, allowing you to keep the player's state in sync with your own backend.

Webhook events

Event	When it fires	What you should do
`player.update`	A player's ban status changes — the player is banned or unbanned	Block or restore the player's access in your game

Today the ban status is the only tracked field. The payload carries only the fields that changed, so treat the set of event_data keys as open: Aghanim can start tracking more player fields without prior notice.

Requirements

To use player update webhooks 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.
Tolerate repeated deliveries — this event is delivered at least once and carries no idempotency_key.
Respond with 2xx status codes if the event was processed successfully, and 4xx or 5xx for errors.

Configuration

Develop a function for the player.update webhook processing.
Make your endpoint available.
Register your endpoint within Aghanim account → Game → Webhooks → Add webhook by choosing the player update event type.

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

Trigger values

Value	Description
`dashboard.player.update`	When a player is banned or unbanned through the Aghanim Dashboard.
`s2s.player.update`	When a player's ban status is changed via the Update Player S2S API.
`test`	When using the "Send test event" in the Dashboard.

See the full events and triggers matrix for how player.update relates to other event types.

Request schema

Below is an example of an player.update 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": "player.update",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "banned": true,
    "banned_reason": "chargeback"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "dashboard.player.update",
  "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": "player.update",
      "event_data": {
        "player_id": "2D2R-OP3C",
        "banned": true,
        "banned_reason": "chargeback"
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": null,
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "dashboard.player.update",
      "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, `player.update` in this case.
`event_time`	`number`	The time the event was sent, in Unix epoch time. May differ across duplicate deliveries of the same event.
`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`	`object\|null`	Contextual information about the event.

The EventData schema

Key	Type	Description
`player_id`	`string`	The unique Player ID chosen for player authentication. Sent unless the game uses Composite Authorization.
`player`	`object`	Player ID components when using Composite Authorization. Sent instead of `player_id`.
`banned`	`boolean`	Whether the player is banned, as of `event_time`. Present only when the ban status changed.
`banned_reason`	`string\|null`	The ban reason as provided by the ban source. `null` if the player is not banned or no reason was given. Present only when the ban status changed.

Deliveries are not ordered

Apply each field value as of the event's event_time, treating the latest event_time per field as the current value, and ignore an event whose event_time is older than the one you already applied. A player banned and then unbanned in quick succession produces two events that may arrive in any order, and a failed delivery is retried for hours. Because event_time has one-second resolution, two changes within the same second are indistinguishable in ordering.

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