Skip to main content

​
Overview

Webhooks allow you to receive real-time notifications when events occur in GameBoost, such as when customers purchase orders or when reports are issued. Instead of polling the API for updates, webhooks push notifications directly to your application.
All destinations, signing secrets, deliveries, and retries are managed through your webhook portal at outpost.gameboost.com.

​
Benefits of Webhooks

Real-time Updates

Receive instant notifications when events occur, keeping your application in sync

Reduced API Calls

Eliminate the need for polling, dramatically reducing your API usage

Multiple Destinations

Fan out the same events to webhooks, AWS SQS/Kinesis/S3, GCP Pub/Sub, RabbitMQ, Kafka, Azure Service Bus and more

Reliable Delivery

Automatic retries with exponential backoff, manual replays, and per-destination alerts

​
Setting Up Webhooks

All webhook configuration is done in the GameBoost webhook portal. You don’t need to manage webhooks from the Partner Dashboard anymore.
1

Open the webhook portal

In the Partner Dashboard, go to Settings → Developers → Webhooks. Clicking Webhooks redirects you to outpost.gameboost.com.
2

Create a destination

Click New Destination and select Webhook as the destination type.Provide:
  • URL: The HTTPS endpoint where events will be delivered
  • Topics: The event topics you want to subscribe to (for example account.order.purchased, order.report.issued)
  • Filters (optional): JSON path filters to only receive events matching a condition
Webhook URLs must use HTTPS. HTTP endpoints are rejected.
3

Copy the signing secret

When the destination is created, a signing secret is generated. Copy it and store it securely (environment variable, secrets manager) — you’ll use it to verify incoming requests.Secrets can be rotated at any time from the destination detail view. During rotation, the previous secret remains valid for a grace period so you can update both old and new secrets without dropping events.
4

Inspect deliveries

The portal shows every delivery attempt, the request/response bodies, headers, and any errors. You can manually retry any failed event from the same view.

​
Webhook Payload Structure

All webhook events follow a consistent structure: 
{
  "event": "account.order.purchased",
  "payload": {
    "id": 123,
    "status": "in_delivery",
    "price_eur": "..."
  }
}

​
Payload Fields

​
event
string
required
The type of event that occurred (e.g., account.order.purchased, order.report.issued). This value also appears in the x-gameboost-topic header.
​
payload
object
required
The event data containing the resource that triggered the webhook. Fields vary based on the event type.

​
Request Headers

Every webhook request includes the following headers:
HeaderDescriptionExample
x-gameboost-event-idUnique identifier for the event. Use it for idempotency.evt_s6UFBLnU5fq1DRXFiwRGLo5Hrv
x-gameboost-topicThe event topic.account.order.purchased
x-gameboost-timestampISO 8601 timestamp of when the event was generated.2026-05-27T11:46:54Z
x-gameboost-signatureHMAC-SHA256 signature of the raw request body, hex-encoded.3c808417736db6edb7b8794e0eb006d7d693d6003ee339bc41f8e2...
user-agentAlways GameBoost Server.GameBoost Server
The header prefix has changed from the legacy Signature header to x-gameboost-* headers. If you previously verified webhooks against the legacy header, update your code to read x-gameboost-signature and the related headers above.

​
Available Webhook Events

GameBoost publishes webhooks for various events across your account. See the complete reference:

View All Webhook Events

Explore detailed documentation for each webhook event type

​
Verifying Webhook Signatures

The signature is the HMAC-SHA256 of the raw, unparsed request body using your destination’s signing secret, encoded as a lowercase hex string. 
signature = hex(HMAC_SHA256(secret, raw_request_body))
Always verify signatures against the raw bytes of the request body — parsing and re-serializing the JSON will change the bytes and break verification. 
const crypto = require('crypto');
const express = require('express');

const app = express();

// IMPORTANT: capture the raw body, not the parsed JSON
app.post(
  '/webhooks/gameboost',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('x-gameboost-signature');
    const expected = crypto
      .createHmac('sha256', process.env.GAMEBOOST_WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    const valid =
      signature &&
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

    if (!valid) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString('utf8'));
    res.status(200).json({ received: true });

    setImmediate(() => processWebhook(event));
  }
);
Always verify webhook signatures in production. Without verification, anyone who discovers your endpoint can post arbitrary events to it.

​
Retries and Delivery Guarantees

GameBoost guarantees at-least-once delivery. Failed deliveries are retried automatically using an exponential backoff schedule. A webhook is considered successfully delivered when your endpoint:
  1. Returns a 2xx status code (200–299)
  2. Responds within the delivery timeout
Any other response (non-2xx, timeout, connection error) is treated as a failure and retried.

​
Manual Retries

You can manually retry any individual event or bulk-retry a range of events from outpost.gameboost.com under the destination’s Events tab.

​
Failure Alerts and Auto-Disable

Delivery health is monitored per destination. If a destination accumulates a high consecutive failure rate, you’ll receive an alert and the destination may be automatically disabled to protect your endpoint from being overwhelmed when it comes back up.
Return a 2xx response as quickly as possible, then process the event asynchronously. Long-running synchronous handlers cause timeouts and duplicate deliveries.

​
Best Practices

Return 200 immediately and process the event in the background. Don’t wait for database writes, downstream APIs, or expensive computation.
app.post('/webhooks/gameboost', (req, res) => {
  res.status(200).json({ received: true });
  setImmediate(() => processWebhook(req.body));
});
Events are delivered at-least-once, so the same event may arrive more than once. Persist the x-gameboost-event-id value and skip events you’ve already processed.
const eventId = req.header('x-gameboost-event-id');
if (await alreadyProcessed(eventId)) return res.status(200).end();
await markProcessed(eventId);
Parse JSON only after verification. If your framework auto-parses request bodies, configure it to expose the raw bytes (for example, express.raw() in Express).
In the portal, subscribe only to the topics you need and use destination-level filters to drop events you don’t care about. This reduces noise and load on your endpoint.

​
Using Hookdeck for Webhook Management

For production applications, we recommend using Hookdeck to manage your webhooks reliably.

Hookdeck

Hookdeck provides webhook infrastructure with automatic retries, monitoring, and debugging

​
Beyond Webhooks: Other Destination Types

You can also deliver the same events to destinations other than HTTP webhooks — useful if you’d rather consume events from a queue or stream than expose a public endpoint.
DestinationUse case
WebhookHTTP POST to your endpoint (default)
HookdeckPoweful webhook ingest service
AWS SQSQueue events for a worker fleet
AWS KinesisStream events into a data pipeline
AWS S3Archive events as objects in a bucket
GCP Pub/SubPublish to a Pub/Sub topic
Azure Service BusSend to a queue or topic
RabbitMQ (AMQP)Push to a RabbitMQ exchange
KafkaSend to a Kafka topic
Create any of these from the New Destination flow in outpost.gameboost.com.

​
Troubleshooting

  • Verify your endpoint URL in outpost.gameboost.com is correct and uses HTTPS.
  • Confirm your endpoint is reachable from the public internet (no firewall, IP allowlist, or VPN blocking traffic).
  • Check the destination’s Events tab — failed deliveries will show the HTTP response and error.
  • Verify the signature against the raw request body, not a re-serialized JSON string.
  • Make sure you’re using the correct signing secret for that destination (it differs per destination).
  • If you recently rotated the secret, update your application config — both old and new secrets are accepted during the rotation window.
  • Compare against x-gameboost-signature (the legacy Signature header is no longer sent).
Duplicates are expected with at-least-once delivery. De-duplicate using x-gameboost-event-id.
If a destination is disabled due to repeated failures, fix your endpoint and re-enable it from the portal. Pending events can be replayed in bulk from the Events tab.

​
Security Checklist

  • Use HTTPS only (HTTP endpoints are rejected)
  • Verify x-gameboost-signature on every request, against the raw body
  • Store signing secrets in a secrets manager — never in source control
  • Rotate signing secrets periodically from the portal
  • Use x-gameboost-event-id for idempotency to safely handle retries

​
Next Steps

Webhook Events

View all available webhook events and their payloads

Webhook Portal

Manage destinations, secrets, and inspect deliveries

Rate Limiting

Learn about API rate limits

Authentication

Review authentication setup