Receiving Event Notifications via Webhooks

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):

Your secure Webhook Endpoint URL (HTTPS required) where your system will listen for incoming notifications.

An API Key (optional) 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.

Upon saving your configuration for the first time, Game Loom will generate a Secret Key and display it once. This secret is used to sign every webhook payload with HMAC-SHA256 via the X-Webhook-Signature header, enabling you to cryptographically verify the authenticity and integrity of each request.

Webhook section in Settings page

Store the Secret Key securely as soon as it is displayed — it will not be shown again. If you lose it, you can regenerate a new one from the dashboard, but the previous key will be invalidated immediately.

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 event details, user ID, event-specific data, and pre-configured localized notification content. This payload is signed with HMAC-SHA256 using your Secret Key and sent via an HTTP POST request to your registered Webhook Endpoint URL with the X-Webhook-Signature header (and the X-API-Key header if you configured one).

Your Action: Your webhook endpoint receives this request

Verify the X-Webhook-Signature header to ensure the request is authentic and untampered (see Webhook Security below).

Optionally verify the X-API-Key header if you configured one.

Process the payload (which includes the specific user ID, event-specific data, 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).

Use the eventId field as an idempotency key to handle potential retries gracefully.

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):

Within the Admin Dashboard, navigate to the "Notifications"

Click on Create Notification.

You will see a list of available notification trigger events

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:

{
  "eventId": "string", // A unique identifier for this event. Use as an idempotency key for retries.
  "eventType": "string", // The name of the trigger that fired (e.g., "RewardsLevelEarned").
  "clientId": "string", // Your company's unique identifier in Game Loom.
  "userId": "string", // The unique identifier of the user in your system for whom the event occurred.
  "occurredAt": "string", // ISO 8601 UTC timestamp of when the event originally occurred.
  "timeSensitive": "boolean", // Indicates if the original event was deemed time-sensitive by our system.
  "data": { // Event-specific metadata as key-value string pairs (varies by eventType).
    // Example for "RewardsLevelEarned":
    // "levelId": "lvl-123",
    // "levelName": "Gold Tier",
    // "amount": "500"
  },
  "customMessages": { // The localized notification content you configured for this trigger.
    // Example for "en":
    // "en": {
    //   "Title": "Configured Title in English",
    //   "Body": "Configured Body in English"
    // },
    // Example for "ar":
    // "ar": {
    //   "Title": "Configured Title in Arabic",
    //   "Body": "Configured Body in Arabic"
    // }
  },
  "sentAt": "string" // ISO 8601 UTC timestamp of when the notification was dispatched from our system.
}

Example Payload Sent (based on "RewardsLevelEarned" config):
If the "RewardsLevelEarned" event triggers for userId: "user123", and you have configured English and Arabic notification content, the payload sent to your webhook would look like this:

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "RewardsLevelEarned",
  "clientId": "your-company-uuid",
  "userId": "user123",
  "occurredAt": "2025-05-31T14:30:00Z",
  "timeSensitive": false,
  "data": {
    "levelId": "lvl-gold-tier",
    "levelName": "Gold Tier",
    "amount": "500"
  },
  "customMessages": {
    "en": {
      "Title": "Level Up!",
      "Body": "You've reached a new level!"
    },
    "ar": {
      "Title": "مستوى جديد!",
      "Body": "لقد وصلت إلى مستوى جديد!"
    }
  },
  "sentAt": "2025-05-31T14:30:02Z"
}

📌

Your backend should parse this payload. The userId identifies the target user in your system. The customMessages object provides the pre-configured, localized content ready for you to use with your notification sender. You might select the appropriate language from the customMessages object based on the end-user's language preference stored in your system, or use a default. The data object provides event-specific context (e.g., badge name, points earned) that you can optionally use for further customization.

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 and scheduled for retry.

Retry Mechanism

If your endpoint returns a non-2xx status code or the request times out, Game Loom will automatically retry delivery:

Maximum attempts: 5 (1 initial + 4 retries)

Retry interval: 5 minutes between each attempt

Maximum delivery window: ~20 minutes from first failure to final attempt

Each retry carries the same , so your endpoint should use this field as an idempotency key to avoid processing the same eventId notification twice.

Webhook Security

Verifying the Webhook Signature (Recommended)

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the raw request body. To verify:

Retrieve the Header: Extract the value of the X-Webhook-Signature header from the incoming HTTP request.

Compute the Expected Signature: Using the Secret Key you received during webhook setup, compute the HMAC-SHA256 hash of the raw request body (before any JSON parsing). Convert the result to a lowercase hexadecimal string.

Compare: Compare the computed signature against the received header value.

Action:

If the signatures match, the request is authentic and unmodified. Proceed with processing the payload.

If the signatures 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.

Always use a constant-time comparison function when comparing signatures to prevent timing attacks.

Verifying the API Key (Optional)

If you provided an API Key during webhook configuration, it will be included in the X-API-Key header of every request. You can use this as an additional layer of verification:

Retrieve the Header: Extract the value of the X-API-Key header from the incoming HTTP request.

Compare with Your Stored Key: Compare this received value against the API Key you configured in the Admin Dashboard.

Action:

If the keys match, proceed with processing.

If the keys do not match, or if the header is missing, respond with an HTTP 401 Unauthorized or 403 Forbidden status code.

📌

HMAC-SHA256 signature verification is the recommended primary method for authenticating webhook requests, as it verifies both authenticity and payload integrity. The API Key provides a convenient additional check but does not verify that the payload has not been tampered with.

Receiving Event Notifications via Webhooks

Overview of the Notification Flow#

Webhook Configuration (Admin Dashboard):#

Notification Preferences Configuration (Admin Dashboard):#

Event Trigger in Our System:#

Preference Check & Content Retrieval:#

HTTP POST to Your Webhook:#

Your Action: Your webhook endpoint receives this request#

Acknowledgement:#

Configuring Notification Preferences (Content & Triggers):#

Notification Payload Sent to Your Webhook:#

Expected Response from Your Webhook#

Retry Mechanism#

Webhook Security#

Verifying the Webhook Signature (Recommended)#

Verifying the API Key (Optional)#

Overview of the Notification Flow

Webhook Configuration (Admin Dashboard):

Notification Preferences Configuration (Admin Dashboard):

Event Trigger in Our System:

Preference Check & Content Retrieval:

HTTP POST to Your Webhook:

Your Action: Your webhook endpoint receives this request

Acknowledgement:

Configuring Notification Preferences (Content & Triggers):

Notification Payload Sent to Your Webhook:

Expected Response from Your Webhook

Retry Mechanism

Webhook Security

Verifying the Webhook Signature (Recommended)

Verifying the API Key (Optional)