Implementing Your Webhook Endpoint

To receive game events, your system must expose an HTTPS endpoint that accepts the webhook notifications we deliver. This page covers the endpoint requirements, the payload you will receive, how to respond, and how delivery and retries work.

Authentication

We authenticate each delivery to your endpoint using the method you configured in your subscription. Validate it on every incoming request.

Type	Required Fields	Description
BEARER	apiKey	API key sent in the `Authorization` header as a Bearer token
BASIC	username, password	HTTP Basic authentication with username and password
NONE	none	No authentication (not recommended for production)

Webhook Payload

Each delivery is a POST request whose body is described by the schema below.

Delivery Sample:

curl -i -X POST \
  https://your-domain.com/webhook/game-events \
  -H 'Content-Type: application/json' \
  -d '{
    "roundId": "12345678-abcd-1234-efgh-123456789012",
    "gameId": "rp_12",
    "playerId": "player123",
    "timestamp": "2026-09-15T10:30:00.123",
    "bet": 1.5,
    "currencyCode": "EUR",
    "events": [
      "COIN",
      "FEATURE"
    ],
    "actionId": "1054417e-487e-46d8-ba99-27e4ee8e86a7"
  }'

Payload Schema:

roundIdstringrequired

Unique identifier for the game round.

Example:"12345678-abcd-1234-efgh-123456789012"

gameIdstringrequired

The game identifier.

Example:"rp_12"

playerIdstringrequired

External player identifier.

Example:"player123"

timestampstringrequired

When the event occurred, in UTC, without a zone offset.

Example:"2026-09-15T10:30:00.123"

betnumberrequired

Bet amount of the action in major currency units (e.g. 1.50 for EUR).

Example:1.5

currencyCodestringrequired

Currency code.

Example:"EUR"

eventsArray of stringsrequired

The event types that occurred during this action.

Example:

[
  "COIN",
  "FEATURE"
]

actionIdstring, (uuid)required

Unique identifier for this specific action; use it to detect duplicate deliveries.

Example:"1054417e-487e-46d8-ba99-27e4ee8e86a7"

Expected Response

Your endpoint acknowledges each delivery with its HTTP status code:

Status	Meaning	Retried?
`200 OK`	Notification processed successfully	No — acknowledged
`4xx`	Permanent failure (e.g. validation error)	No
`5xx`	Temporary failure	Yes — with exponential backoff

Endpoint Requirements

You need to provide an HTTPS endpoint capable of receiving POST requests with application/json content type. Configure the endpoint URL and its authentication when you create or update your subscription.

URL Format: Any HTTPS URL (e.g., https://your-domain.com/webhook/game-events)

HTTP Method: POST

Content-Type: application/json

Authentication: Configured by you during subscription creation (see the supported types above).

Default Endpoint

Providing a callback URL is optional. If you do not provide one when creating your subscription, events are delivered to your default endpoint: your existing wallet base URL, reusing the authentication credentials already configured for your account. The full path is $wallet_url/v1/game-action-events, and no additional setup is required.

Delivery & Retries

We continuously deliver webhooks to your configured endpoint with automatic retry handling.

Reliable Delivery: Automatic retries for up to 7 days
Exponential Backoff: Increasing delays between retries (prevents overwhelming your system)
Error Handling: Permanent failures (4xx errors) are not retried
Authentication: Uses the authentication method configured in your subscription (BEARER, BASIC, or NONE)

Best Practices

Respond quickly: Return 200 OK as soon as possible (under 1 second)
Handle duplicates: Use actionId to detect duplicate deliveries
Process asynchronously: Queue webhook processing if you need time to process
Monitor failures: Track 4xx responses to identify integration issues
Validate payloads: Always validate incoming webhook structure