Webhooks

Webhooks are designed to receive platform feedback.

They are received when:

a new game has started
a new user has registered
a user has updated their details
a user has claimed a prize

Workflow

stateDiagram-v2
    direction LR
    [*] --> PLAY_GAME
    PLAY_GAME --> REGISTER_PLAYER
    REGISTER_PLAYER --> UPDATE_PLAYER
    REGISTER_PLAYER --> CLAIMED_PRIZE
    UPDATE_PLAYER --> CLAIMED_PRIZE
    CLAIMED_PRIZE --> [*]

Getting Started

To start receiving webhook feedback, you must register your API URL in your admin panel.

Register your webhook

First, navigate to the admin panel in "Settings" > "Callback URLs" and click on "Create a callback URL". Fill out the form and submit it. The "Verification token" is a token of your choice to verify requests coming from our servers.

Prepare your API

Before receiving your first events, we will validate your endpoint by sending a verification request.

Verification request

A verification request is sent periodically to check the availability of your endpoint.

Path for verification request

GET

/?verify_token={verifyToken}&challenge={challenge}

Query string parameters

Field	Type	Required	Description
`verify_token`	string	Required	The verification token register upon webhook registration
`challenge`	integer	Required	The challenge value you have to return

GET

/?verify_token=d2052c79-7c48-41e5-b710-57311dfa630c&challenge=12345

Expected response

Response must be challenge value as plain text and status code must be 200 OK.

Events request

We send a request to your endpoint when an event occurs for your company.

Path for events request

POST

/?verify_token={verifyToken}

Query path parameters

Field	Type	Required	Description
`verify_token`	string	Required	The verification token registered upon webhook registration

POST

/?verify_token=d2052c79-7c48-41e5-b710-57311dfa630c

JSON Body parameters

Field	Type	Required	Description
`messageId`	string	Required	The message identifier
`events`	Event[]	Required	The events

Event type

Field	Type	Required	Description
`eventId`	string	Required	The event identifier
`eventType`	EventType	Required	The event type
`player`	Player	Required	The player
`establishment`	Establishment	Required	The establishment
`prize`	Prize		The claimed prize (for PLAY_GAME and CLAIMED_PRIZE events)
`play`	Play		The play (for PLAY_GAME and CLAIMED_PRIZE events)
`game`	Game		The game (for PLAY_GAME and CLAIMED_PRIZE events)

{
  "eventId": "5647a0b0-631c-437c-8885-80038cc56ceb",
  "eventType": "REGISTER_PLAYER",
  "createdAt": "2025-05-20T15:25:44Z",
  "player": {
    "playerId": "0e0d2a3a-0b9e-44f9-8b4c-b093c1fe03e4",
    "partnerUserId": "11111111",
    "givenName": "foo",
    "familyName": "bar",
    "email": "foo.bar@suggpro.com",
    "phoneNumber": "+33123456789"
  },
  "prize": null
}

json

EventType type

EventType is an enum with the following values:

PLAY_GAME
REGISTER_PLAYER
UPDATE_PLAYER
CLAIMED_PRIZE

Player type

Field	Type	Required	Description
`playerId`	string	Required	The player identifier
`partnerUserId`	string		The partner user identifier
`givenName`	string		The user given name
`familyName`	string		The user family name
`email`	string		The user email
`phoneNumber`	string		The user phone number (in E.164 format)
`postalCode`	string		The postal code
`postalCodeLabel`	string		The postal code label (mainly city name)
`country`	string		The country code (in ISO 3166-1 alpha-2 format)
`latitude`	float64		The latitude
`longitude`	float64		The longitude

{
  "playerId": "0e0d2a3a-0b9e-44f9-8b4c-b093c1fe03e4",
  "partnerUserId": "11111111",
  "givenName": "foo",
  "familyName": "bar",
  "email": "foo.bar@suggpro.com",
  "phoneNumber": "+33123456789"
}

json

Establishment type

Field	Type	Required	Description
`establishmentId`	string	Required	The establishment identifier
`name`	string	Required	The establishment name

{
  "establishmentId": "a2673bdc-3d24-4890-816c-2f5c02de156e",
  "name": "Test"
}

json

Prize type

Field	Type	Required	Description
`prizeId`	string	Required	The prize identifier
`type`	PrizeType	Required	The prize type
`name`	string	Required	The prize name

{
  "prizeId": "4a8670c9-881e-4cfe-ab94-50a0e59dcbeb",
  "type": "PHYSICAL",
  "name": "a nice gift"
}

json

PrizeType type

PrizeType is an enum with the following values:

PHYSICAL
VIRTUAL

Play type

Field	Type	Required	Description
`playId`	string	Required	The play identifier
`language`	language code	Required	The language code (in ISO 639-1 format)
`claimLink`	string	Required	The link address to claim his prize
`claimMinimumAt`	date		The minimum date to claim his prize (in RFC3339 format)
`claimMaximumAt`	date		The maximum date to claim his prize (in RFC3339 format)
`claimedAt`	date		The claimed date (in RFC3339 format)
`createdAt`	date		The initial play date (in RFC3339 format)

{
  "playId": "bb8e586f-5ac4-4c7a-9ad0-d99e4f738060",
  "language": "FR",
  "claimLink": "https://test.gaming.suggpro.com/0e0d2a3a-0b9e-44f9-8b4c-b093c1fe03e4/fr/14e677fa-248b-4bee-bb74-dce5f3170f95/claim/4a8670c9-881e-4cfe-ab94-50a0e59dcbeb",
  "claimMaximumAt": null,
  "claimMinimumAt": "2025-09-29T14:40:41Z",
  "createdAt": "2025-09-29T14:39:54Z"
}

json

Game type

Field	Type	Required	Description
`gameId`	string	Required	The game identifier
`name`	string	Required	The name

{
  "gameId": "b53d951b-c65f-42fb-b1ab-38527a583418",
  "name": "Venez jouer avec nous"
}

json

Expected response

Response must have a status code between 200 and 299.

If the response code is different, we will retry sending request up to four times at different timings. If we can't succeed, your event will be discarded.

Access log

To check and debug your API, you can check logs in your admin panel by clicking on "Display logs".

Last update at: 2025/10/01 14:05:48