Webhook Callbacks

Topaz Games API uses webhook callbacks to communicate important events to your platform, such as requesting player balance or notifying about betting and winning events. This guide explains how to handle these webhooks securely and provides example implementations in JavaScript.

Overview

Webhook callbacks are HTTP requests sent from Topaz Games servers to your application's endpoints. They are used for:

• Balance Inquiries: Requesting the current balance of a player.
• Bet Notifications: Notifying your system when a player places a bet.
• Win Notifications: Notifying your system when a player wins.

To ensure security and integrity, each webhook request is signed using HMAC-SHA1. Your application must verify this signature before processing the request.

Handling Webhook Events

Supported Actions

• bet: Notification that a player has placed a bet.
• win: Notification that a player has won a game.
• balance: Request for the player's current balance.

Request Parameters

Each webhook request includes the following parameters:

• action: The type of event (e.g., bet, win, balance).
• player_id: The unique identifier of the player.
• game_uuid: The unique identifier of the game.
• amount: The amount of the bet or win.
• currency: The currency of the amount.
• session_id: The unique identifier of the game session.

Security Considerations

To ensure the authenticity of the webhook requests, you must verify the signature provided in the X-Sign header. The signature is generated using HMAC-SHA1 with your client key as the secret key. You can read more about request security in the Request Security guide.

Example of Webhook Notification

Bet Notification

{
    "action": "bet",
    "player_id": "player123",
    "game_uuid": "topaz-mines",
    "amount": 100,
    "currency": "USD",
    "session_id": "1234567890"
}

The response to this notification should be a 200 OK status code :

{
    "status": "success"
}

if the player does not have enough balance to place the bet, the response should be a 401 Unauthorized status code :

{
    "status": "error",
    "error": "INSUFFICIENT_FUNDS",
    "message": "Insufficient balance"
}

Win Notification

{
    "action": "win",
    "player_id": "player123",
    "game_uuid": "topaz-mines",
    "amount": 500,
    "currency": "USD",
    "session_id": "1234567890"
}

The response to this notification should be a 200 OK status code :

{
    "status": "success"
}

Balance Inquiry

{
    "action": "balance",
    "player_id": "player123"
}

The response to this inquiry should be a 200 OK status code :

{
    "balance": 1000,
    "currency": "USD"
}

For any other action, the response should be a 404 Not Found status code :

{
    "status": "error",
    "error": "INVALID_ACTION",
    "message": "Invalid action"
}

or if an error occurs while processing the request, the response should be a 500 Internal Server Error status code :

{
    "status": "error",
    "error": "INTERNAL_ERROR",
    "message": "An internal error occurred"
}