Configure Webhooks

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.

Webhooks reduce API calls dramatically and provide near-instant updates, making them essential for responsive integrations.

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

Better User Experience

Provide immediate feedback to your users about status changes

Reliable Delivery

Automatic retries ensure you don’t miss critical events

Setting Up Webhooks

Configure webhooks directly from your Partner Dashboard:

Navigate to Webhooks Settings

Add a New Webhook Endpoint

Click New Webhook to create a new webhook configuration.You’ll need to provide:

Endpoint URL: The HTTPS URL where you want to receive webhook events
Description: A friendly name to identify this webhook
Events: Select which events you want to receive

Your webhook endpoint must use HTTPS. HTTP endpoints are not supported for security reasons.

Configure Authentication

Copy the secret key to verify webhook authenticity. GameBoost will include this in the webhook signature, allowing you to verify the webhook came from us.

We strongly recommend using webhook signatures to prevent unauthorized webhook calls to your endpoint.

Test Your Webhook

Click Send Test Event to verify your endpoint is working correctly. You should receive a test webhook payload at your endpoint.If the test succeeds, your webhook is ready to receive live events!

Webhook Payload Structure

All webhook events follow a consistent structure:

{
  "event": "currency.order.purchased",
  "payload": {
    "id": 123,
    "status": "in_delivery",
    "price_eur": "..."
  }
}

Payload Fields

event

string

required

The type of event that occurred (e.g., currency.order.purchased, order.report.issued)

payload

object

required

The event data containing the resource that triggered the webhook. Fields vary based on the event type.

Available Webhook Events

GameBoost sends webhooks for various events in your seller account. See the complete list of webhook events and their payloads:

View All Webhook Events

Explore detailed documentation for each webhook event type

Webhook Signatures

All webhooks include a Signature header containing an HMAC SHA-256 signature. You should verify this signature to ensure the webhook came from GameBoost.

Signature Verification

The signature is computed as follows:

HMAC-SHA256(webhook_payload, webhook_secret)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Always verify webhook signatures in production to prevent unauthorized parties from sending fake webhooks to your endpoint.

Webhook Retries

GameBoost automatically retries failed webhook deliveries to ensure reliable event delivery using an exponential backoff strategy.

Retry Strategy

Attempt	Wait Time	Description
1	Immediate	Initial delivery attempt
2	~10 seconds	First retry
3	~100 seconds	Second retry (final attempt)

After 3 failed attempts, the webhook will be marked as failed and no further retries will be attempted for that event.

Successful Delivery Criteria

A webhook is considered successfully delivered if your endpoint:

Responds within 3 seconds
Returns a 2xx status code (200-299)

Return a 200 status code as quickly as possible, then process the webhook asynchronously. This prevents timeouts and duplicate deliveries.

Handling Retries

Implement idempotency to ensure webhook events are only processed once, even if they’re retried:

const processedEvents = new Set();

app.post('/webhooks/gameboost', async (req, res) => {
  const webhook = req.body;

  // Create a unique identifier for this webhook
  const webhookId = `${webhook.event}_${webhook.payload.id}`;

  // Check if we've already processed this event
  if (processedEvents.has(webhookId)) {
    console.log(`Webhook ${webhookId} already processed (retry)`);
    return res.status(200).json({ received: true });
  }

  // Process the webhook
  await processWebhook(webhook);

  // Mark as processed
  processedEvents.add(webhookId);

  res.status(200).json({ received: true });
});

Best Practices

Return 200 quickly

Process webhooks asynchronously and return a 200 status code immediately. Don’t wait for database operations or external API calls to complete.

app.post('/webhooks/gameboost', async (req, res) => {
  // Return 200 immediately
  res.status(200).json({ received: true });

  // Process asynchronously
  setImmediate(async () => {
    try {
      await processWebhook(req.body);
    } catch (error) {
      console.error('Webhook processing failed:', error);
    }
  });
});

Implement idempotency

Store processed webhook identifiers and skip events you’ve already processed. This prevents duplicate processing if a webhook is retried.

// Using a database
async function isWebhookProcessed(event, payloadId) {
  const webhookId = `${event}_${payloadId}`;
  const result = await db.query(
    'SELECT id FROM processed_webhooks WHERE webhook_id = ?',
    [webhookId]
  );
  return result.length > 0;
}

async function markWebhookProcessed(event, payloadId) {
  const webhookId = `${event}_${payloadId}`;
  await db.query(
    'INSERT INTO processed_webhooks (webhook_id, processed_at) VALUES (?, NOW())',
    [webhookId]
  );
}

Verify signatures

Always verify the Signature header to ensure webhooks are authentic.

const signature = req.headers['signature'];
if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Log webhook events

Log all incoming webhooks for debugging and auditing purposes.

console.log({
  timestamp: new Date().toISOString(),
  event: webhook.event,
  payload_id: webhook.payload.id
});

Handle failures gracefully

If processing fails, log the error but still return 200 to prevent retries. You can reprocess failed events later from your logs.

try {
  await processWebhook(webhook);
} catch (error) {
  console.error('Webhook processing failed:', {
    event: webhook.event,
    payload_id: webhook.payload.id,
    error: error.message
  });

  // Store failed webhook for later reprocessing
  await storeFailedWebhook(webhook, error);
}

// Still return 200
res.status(200).json({ received: true });

Test thoroughly

Use the test webhook feature in the Partner Dashboard to verify your endpoint works correctly before going live.

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

Troubleshooting

Webhooks not being received

Possible causes:

Your endpoint is not accessible from the internet
Firewall or security group blocking requests
Incorrect endpoint URL configured
Server not responding within 3 seconds

Solutions:

Verify your endpoint URL is correct and accessible
Check firewall rules and allowlist GameBoost User-Agent
Test with the “Send Test Event” button
Ensure your endpoint returns 200 quickly

Receiving duplicate webhooks

Cause: Your endpoint is not returning 200 quickly enough, causing GameBoost to retrySolution: Implement async processing and return 200 immediately

Signature verification failing

Possible causes:

Using wrong webhook secret
Modifying payload before verification
Character encoding issues

Solutions:

Verify you’re using the correct secret from Partner Dashboard
Verify signature before parsing or modifying the payload
Use the raw request body for verification

High failure rate

Check:

Server logs for errors
Response times (should be < 3 seconds)
Server capacity and resource usage
Database connection issues

Consider using Hookdeck for more reliable delivery

Webhook Security

Never expose your webhook secret in client-side code or version control systems.

Security Checklist

✅ Use HTTPS only (HTTP endpoints are rejected)
✅ Verify webhook signatures on every request
✅ Store webhook secrets securely (environment variables, secrets manager)
✅ Validate event data before processing
✅ Implement rate limiting on your webhook endpoint
✅ Log suspicious webhook activity
✅ Rotate webhook secrets periodically

Next Steps

Webhook Events

View all available webhook events and their payloads

API Reference

Explore all available API endpoints

Rate Limiting

Learn about API rate limits

Authentication

Review authentication setup

Getting Started

REST API

Webhooks

Overview

Benefits of Webhooks

Real-time Updates

Reduced API Calls

Better User Experience

Reliable Delivery

Setting Up Webhooks

Webhook Payload Structure

Payload Fields

Available Webhook Events

View All Webhook Events

Webhook Signatures

Signature Verification

Webhook Retries

Retry Strategy

Successful Delivery Criteria

Handling Retries

Best Practices

Using Hookdeck for Webhook Management

Hookdeck

Troubleshooting

Webhook Security

Security Checklist

Next Steps

Webhook Events

API Reference

Rate Limiting

Authentication

Getting Started

REST API

Webhooks

​Overview

​Benefits of Webhooks

Real-time Updates

Reduced API Calls

Better User Experience

Reliable Delivery

​Setting Up Webhooks

​Webhook Payload Structure

​Payload Fields

​Available Webhook Events

View All Webhook Events

​Webhook Signatures

​Signature Verification

​Webhook Retries

​Retry Strategy

​Successful Delivery Criteria

​Handling Retries

​Best Practices

​Using Hookdeck for Webhook Management

Hookdeck

​Troubleshooting

​Webhook Security

​Security Checklist

​Next Steps

Webhook Events

API Reference

Rate Limiting

Authentication

Overview

Benefits of Webhooks

Setting Up Webhooks

Webhook Payload Structure

Payload Fields

Available Webhook Events

Webhook Signatures

Signature Verification

Webhook Retries

Retry Strategy

Successful Delivery Criteria

Handling Retries

Best Practices

Using Hookdeck for Webhook Management

Troubleshooting

Webhook Security

Security Checklist

Next Steps