Webhooks Overview

Webhooks let your server receive real-time HTTP callbacks whenever key events happen in GamifyHost — such as points being awarded or a game being played. Instead of polling the API, you register a URL and GamifyHost pushes event data to it.

Prerequisites

Before setting up webhooks, you need to:

1. Create a GamifyHost account and log in to the dashboard
2. Create an app from the dashboard — each webhook is scoped to a specific app
3. Navigate to your app’s Webhooks settings to register endpoints

Webhook management is only available through the dashboard. All management endpoints use session-based authentication (your dashboard login), not API keys.

How It Works

1. Create an app in the GamifyHost dashboard
2. Navigate to the app’s webhook settings and register a URL
3. Subscribe to specific events (e.g. points.awarded, game.played)
4. When an event fires, GamifyHost sends a signed POST request to your URL
5. Your server verifies the signature and processes the payload
6. Respond with 2xx to acknowledge receipt

GamifyHost                          Your Server
    │                                    │
    │  Event fires (game.played)         │
    │                                    │
    ├──── POST /your-webhook-url ───────▶│
    │     X-Webhook-Signature: sha256=…  │
    │     X-Webhook-Event: game.played   │
    │     { event, data, timestamp }     │
    │                                    │
    │◀──── 200 OK ──────────────────────┤
    │                                    │

Events

Event	Fired When
points.awarded	Points are awarded to a user via POST /v1/points/award
game.played	A user plays a game via POST /v1/games/play

Delivery Guarantees

• Deliveries are retried up to 5 times with 3-minute intervals between attempts
• Each delivery attempt is logged with status, response code, duration, and error details
• Webhooks that repeatedly fail have their failureCount incremented
• You can inspect delivery history via the API or dashboard

Security

Every webhook request is signed with HMAC-SHA256 using a secret generated at webhook creation time. See Webhook Security for verification details.

Webhook Management

Webhooks are managed per-app through the GamifyHost dashboard. All management endpoints require partner authentication (session-based from your dashboard login) — they are not accessible via public or secret API keys. You must first create an app in the dashboard before you can register webhooks for it.

See Webhook Management API for the full CRUD reference.

Payload Format

All webhook payloads follow this structure:

{
  "event": "game.played",
  "data": { ... },
  "timestamp": "2025-07-15T10:30:00Z"
}

See Events & Payloads for detailed payload schemas per event type.