To keep your system informed about relevant events occurring within Game Loom (e.g., a user leveling up), we utilize webhooks. When a configured event is triggered for one of your users, our backend will send an HTTP POST request. This request contains the event details, including pre-configured notification content (titles and bodies in specified languages), to a secure HTTPS URL you provide. Your backend is then responsible for processing this information and relaying it to your end-users via your own notification sending mechanisms.Overview of the Notification Flow#
Webhook Configuration (Admin Dashboard):#
1.
Your secure Webhook Endpoint URL (HTTPS required) where your system will listen for incoming notifications.
2.
An API Key that our system will include in the X-API-Key header of every webhook request we send to you. This allows your endpoint to authenticate that the request is genuinely from Game Loom.
Webhook section in Settings page
The API Key you provide for us to call your webhook should be treated as a secret and securely managed by your systems.
Notification Preferences Configuration (Admin Dashboard):#
Enable or disable notifications for that event.
Define the supported languages (e.g., "en", "ar").
Provide the notification title and body content for each supported language.
Event Trigger in Our System:#
When a relevant event occurs for a user associated with your company (e.g., a user achieves a new level).Preference Check & Content Retrieval:#
Our system checks if you have this event type enabled for notifications. If enabled, we retrieve the notification content (titles, bodies, supported languages) you configured for that specific event.HTTP POST to Your Webhook:#
We construct a JSON payload containing the user's ID, the pre-configured localized notification data, and other relevant details. This payload is then sent via an HTTP POST request to your registered Webhook Endpoint URL, with the agreed-upon API Key included in the X-API-Key header.Your Action: Your webhook endpoint receives this request#
Verify the X-API-Key header to ensure the request is from us.
Process the payload (which includes the specific user ID and the localized notification content).
Use this information to trigger a notification to the identified end-user through your own notification delivery systems (e.g., push notifications, email, SMS).
Acknowledgement:#
Your endpoint should respond with an HTTP success status code (e.g., 200 OK) to acknowledge receipt of the notification.Configuring Notification Preferences (Content & Triggers):#
1.
Within the Admin Dashboard, navigate to the "Notifications"
2.
Click on Create Notification.
3.
You will see a list of available notification trigger events
4.
For each trigger event, you can:
Enable/Disable: Toggle whether notifications should be sent for this event.
Supported Languages: Specify an array of language codes (e.g., "en", "es") for which you will provide content.
Localized Content (data): For each supported language, provide the title and body for the notification.
Create new notification preferences
Notification Payload Sent to Your Webhook:#
When a configured and enabled event is triggered, our system will send an HTTP POST request to your Webhook URL with a JSON body structured as follows:{
"userId": "string",
"languages": ["string"],
"data": {
},
"timeSensitive": "boolean",
"sentAt": "string"
}
If the "LevelUp" event (as configured above) triggers for userId: "user123", and the original event was not time-sensitive, the payload sent to your webhook would look like this:{
"userId": "user123",
"languages": ["en", "es"],
"data": {
"en": {
"title": "Level Up!",
"body": "You've reached a new level!"
},
"es": {
"title": "¡Nuevo Nivel!",
"body": "¡Has alcanzado un nuevo nivel!"
}
},
"timeSensitive": false,
"sentAt": "2025-05-31T14:35:17Z"
"idempotencyKey": "unique id for this event"
}
Your backend should parse this payload. The userId identifies the target user in your system. The data object, along with the languages array, provides the pre-configured, localized content ready for you to use with your notification sender. You might select the appropriate language from the data object based on the end-user's language preference stored in your system, or use a default.
Expected Response from Your Webhook#
Success: Your webhook endpoint should respond with an HTTP 200 OK status code to acknowledge successful receipt and basic validation of the notification.
Failure: If your endpoint cannot process the request or encounters an error, it should respond with an appropriate HTTP error code (e.g., 400 Bad Request for payload issues, 500 Internal Server Error for server-side problems on your end).
Timeout: Our system will wait for a response. If no response is received within this time, the request will be considered failed.
Webhook Security#
Verifying Requests from Us To ensure that incoming POST requests to your webhook endpoint are genuinely from Game Loom and not from a malicious actor, you must verify the X-API-Key header:1.
Retrieve the Header: Extract the value of the X-API-Key header from the incoming HTTP request.
2.
Compare with Your Stored Key: Compare this received value against the API Key you configured for us in the Admin Dashboard.
If the keys match, the request is authentic. Proceed with processing the payload.
If the keys do not match, or if the header is missing, do not process the request. Respond with an HTTP 401 Unauthorized or 403 Forbidden status code and log the unauthorized attempt.
