Fraud Reported Webhook

When a payment processor reports fraud on a completed payment, Aghanim sends a fraud.reported webhook to notify your game. This event arrives days or weeks after the original charge, when the card network or issuer retroactively flags a payment as fraudulent.

This webhook is activated through the Fraud reported event, selectable in Game → Webhooks.

Requirements

To use the fraud reported 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 the fraud event was processed successfully, and 4xx or 5xx for denial or errors.

Configuration

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

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

Request schema

Below is an example of an fraud.reported 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": "fraud.reported",
  "event_data": {
    "id": "frd_aBcDeFgHiJkLmNoPqRs",
    "player_id": "2D2R-OP3C",
    "order_id": "ord_eCacpFwavzi",
    "payment_id": "pmt_eFgYpxryeKXpLKfmZstI",
    "fraud_type": "card_stolen",
    "amount": 9499,
    "currency": "USD",
    "payment_method": "cards",
    "reported_at": 1725547595
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "idmpt_aXRlb...JkX2VFS",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": null,
  "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": "fraud.reported",
      "event_data": {
        "id": "frd_aBcDeFgHiJkLmNoPqRs",
        "player_id": "2D2R-OP3C",
        "order_id": "ord_eCacpFwavzi",
        "payment_id": "pmt_eFgYpxryeKXpLKfmZstI",
        "fraud_type": "card_stolen",
        "amount": 9499,
        "currency": "USD",
        "payment_method": "cards",
        "reported_at": 1725547595
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": "idmpt_aXRlb...JkX2VFS",
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": null,
      "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, `fraud.reported` 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`	`object\|null`	Contextual information about the event.

The EventData schema

Field	Type	Description
`id`	string	Unique identifier for the fraud report
`player_id`	string	The player who made the payment
`order_id`	string	The order associated with the payment
`payment_id`	string	The payment that was flagged
`fraud_type`	enum	Normalized fraud category (`card_lost`, `card_stolen`, `unauthorized_card_use`, `counterfeit_card`, `fraudulent_application`, `other`)
`amount`	number	Payment amount in minor currency units
`currency`	string	Payment currency
`payment_method`	string	Payment method used (`cards`, `apple_pay`, `google_pay`, etc.)
`reported_at`	integer	Unix timestamp when the fraud was reported by the payment processor

Recommended handling

Consider proactive refunds: Fraud reports arrive before formal chargebacks. Proactively refunding via the Refund API can avoid chargeback fees.
Flag the player: Track fraud reports per player. Multiple fraud.reported events for the same player may indicate account compromise or abuse.
Revoke items on refund: If you refund, also revoke the granted items via Item Remove.

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