External Reward System Integration#
GameLoom allows you to integrate your own reward systems, such as cashback, points, or any custom reward type, through webhooks.When integrated, GameLoom will notify your system whenever a user becomes eligible for a reward.How It Works#
To enable the integration, configure the following in the Integration page:API Key for request validation
Integrate with your Reward system page in GameLoom
Linking External Rewards to Challenges#
After configuring the integration, your external rewards will be available in the portal and marked with an External tag.External reward tag in GameLoom
Webhook Response#
Below is the payload you should expect when GameLoom sends a reward notification to your system.{
"IdempotencyKey": "abc-123",
"CompanyId": "company-1",
"UserKey": "user-key-42",
"UserPointEventId": "507f1f77bcf86cd799439011",
"PointId": "point-xyz",
"PointName": "Coins",
"Amount": 100,
"ActionType": "Increment",
"Timestamp": "2026-04-12T14:30:00.0000000Z"
}
Notification Logs and Resending#
You can monitor all outgoing reward notifications from the Rewards page.View the delivery status of each notification
Retry failed notifications using the Resend action
Export reconciliation reports for tracking and auditing purposes
Reconciliation section in GameLoom
Webhook outbox section in GameLoom
Retry Behavior#
GameLoom delivers external reward webhooks using an at-least-once delivery model. This means the same event may be sent more than once, so your endpoint must handle duplicate deliveries safely. To do this, use the IdempotencyKey included in every payload. For more details, see Idempotent Processing.HTTP Delivery Attempts#
When GameLoom sends a reward webhook to your endpoint, we may retry the HTTP request several times in quick succession if we encounter a temporary failure, such as:Your server returns a 5xx response
Your server returns 408 Request Timeout
The request times out after approximately 10 seconds
The connection fails for network-related reasons
Temporary Endpoint Protection#
If repeated failures occur across multiple deliveries, GameLoom may temporarily stop sending requests to endpoints that appear unhealthy.In this case, requests may fail fast for a short period, typically around 30 seconds, to avoid overwhelming an unavailable or degraded service.Success Criteria#
A webhook delivery is considered successful only when your endpoint returns a 2xx HTTP response.Any non-2xx response may cause the delivery to be retried according to the retry policy.Scheduled Retries#
If the webhook still fails after the immediate retry attempts, GameLoom keeps the event and retries it later on a scheduled basis.The delay between scheduled retries increases over time using an exponential backoff strategy, based on a default 30-minute interval.Retry delay increases roughly by doubling after each failure
GameLoom retries the event up to 10 times
After that, the event is no longer retried automatically
Manual handling may be required from our side
Retry Processing Job#
GameLoom also runs a periodic job, typically every 30 minutes, to identify events that are due for another delivery attempt.What You Should Implement#
To integrate correctly with GameLoom webhooks, your system should support the following:1. Idempotent Processing#
Because webhook delivery is at least once, the same logical event may be delivered more than once.To safely ignore duplicates:1.
Read the IdempotencyKey from the webhook payload.
2.
Check whether you have already processed that key.
3.
If it has already been processed, return a successful response without applying the reward again.
4.
If it has not been processed, apply the reward and store the key in your system.
UserPointEventId as an additional reference for reconciliation or internal tracking, but IdempotencyKey should be your primary key for duplicate protection.A recommended approach is to store the IdempotencyKey in your database with a uniqueness constraint, so duplicate deliveries can be detected safely and automatically.2. Request Validation#
GameLoom validates webhook requests using the API Key configured in the integration page.Make sure your endpoint validates incoming requests using the API key you configured, and rejects unauthorized requests before processing the payload.