5.5 Webhooks & Delivery

Alert webhooks let your studio send Gamers Lab alert events to your own systems, such as an incident channel, monitoring service, internal dashboard, or automation workflow.

When an alert is created for your tenant, Gamers Lab can send an HTTP POST request to the webhook URL you configure in the dashboard.

5.5.1 When To Use Alert Webhooks

Use alert webhooks when your team wants alerts outside the Gamers Lab dashboard.

Common uses include:

• posting alerts to Slack, Discord, Teams, or PagerDuty,
• sending alert events to your own monitoring system,
• logging high-traffic or large-payload alerts in an internal dashboard,
• starting an internal workflow when a key suddenly spikes.

Webhooks are optional. You can still receive alerts through in-app notifications and email without setting up a webhook.

5.5.2 Create A Webhook In The Dashboard

To create a tenant alert webhook:

1. Open the Gamers Lab dashboard.
2. Select the tenant you want to monitor.
3. Go to the tenant's alerts or webhook settings.
4. Add a new alert webhook.
5. Enter a display name, endpoint URL, and signing secret.
6. Save the webhook and keep it active.

Use an HTTPS endpoint in production. Treat the signing secret like a password.

5.5.3 Endpoint Requirements

Your webhook endpoint should:

A simple pattern is to verify the signature, store or enqueue the event, return 200 OK, and then process the alert in the background.

5.5.4 Payload Format

Gamers Lab sends alert webhooks in this format:

{
  "event": "alert.created",
  "data": {
    "alertId": "<uuid>",
    "tenantId": "<uuid>",
    "companyId": "<uuid or null>",
    "keyType": "api",
    "apiKeyId": "<uuid or null>",
    "gameAuthKeyId": "<uuid or null>",
    "alertType": "rate_spike",
    "windowSeconds": 60,
    "thresholdValue": 300,
    "observedValue": 450,
    "createdAt": "2026-06-05T12:00:00Z"
  }
}

Only one of apiKeyId or gameAuthKeyId is set for a single alert.

5.5.5 Request Headers

Each webhook request includes these headers:

Use X-GL-Idempotency-Key to avoid processing the same delivery twice.

5.5.6 Verify The Signature

Gamers Lab signs each webhook using your webhook signing secret.

To verify a request:

1. Read the raw request body exactly as received.
2. Compute an HMAC-SHA256 signature using your webhook signing secret.
3. Convert the result to lowercase hex.
4. Compare it to the X-GL-Signature header.
5. Reject the request if the signatures do not match.

Signature format:

HMAC-SHA256(key = signing secret, message = raw request body)

Always verify the signature before trusting the payload.

5.5.7 Delivery And Retries

Gamers Lab considers a webhook delivered when your endpoint returns a 2xx HTTP status.

If your endpoint is unavailable or returns a non-2xx response, Gamers Lab retries the delivery a limited number of times with increasing delay. If all retry attempts fail, the delivery is marked as failed and can be reviewed in the dashboard.

Design your endpoint so duplicate deliveries are safe. The same event may be retried if the first attempt fails or times out.

5.5.8 Delivery History And Manual Retry

The dashboard shows recent webhook deliveries for each webhook.

Delivery history can help you troubleshoot:

If a delivery failed permanently, you can retry it from the dashboard after fixing your endpoint.

5.5.9 Best Practices

• Use HTTPS in production.
• Keep the signing secret private.
• Verify X-GL-Signature before processing the payload.
• Return 2xx quickly, then process the alert asynchronously.
• Store X-GL-Idempotency-Key so duplicate deliveries do not create duplicate actions.
• Rotate the signing secret if it may have been exposed.
• Keep your webhook endpoint narrow: only accept the alert events you expect.