Webhooks
Real-time multiplayer server discovery
Available Webhook Events
Subscribe to specific server lifecycle events to trigger alerts, dashboards, or automated scaling pipelines.
Online/Offline Transitions
Fires when a monitored server switches between reachable and unreachable states. Includes uptime duration and last successful query timestamp.
Population Threshold Alerts
Triggers when active player count crosses your defined upper or lower bounds. Ideal for capacity planning and promotional campaigns.
Fresh Network Additions
Dispatched when a new game server registers via the ServerPulse API or passes initial discovery validation. Contains region, game port, and protocol version.
Connection Restoration
Sent after three consecutive failed heartbeat queries resolve. Useful for clearing false-positive outage alerts in your incident management tool.
Payload Structure
All webhook deliveries use HTTP POST with a JSON body. Verify signatures using the x-sp-signature header before processing.
server.status_change Example
{ "event": "server.status_change", "timestamp": "2024-11-15T08:42:11Z", "server_id": "sp_srv_882910", "hostname": "Ironforge-Main-NA", "ip": "198.51.100.44", "port": 27015, "game": "Counter-Strike 2", "previous_state": "offline", "current_state": "online", "player_count": 24, "max_players": 64, "map": "de_ancient", "metadata": { "region": "us-east-1", "protocol": "valve_steam", "heartbeat_latency_ms": 42 } }
Signature Verification
ServerPulse appends a SHA-256 HMAC to every request. Extract the header value, compute HMAC-SHA256 using your webhook secret, and compare against the payload. Mismatches indicate tampering or misconfigured secrets.
Configuration Steps
Route event streams to your internal endpoints in three steps. All configurations persist across API version upgrades.
Generate Webhook Secret
Navigate to Developer > API Keys in your ServerPulse dashboard. Click Rotate Secret to generate a 64-character base64 string. Store this securely in your environment variables.
Define Endpoint & Filters
Submit a POST request to /v2/webhooks with your target URL. Apply event filters to prevent payload bloat. Example: {"events": ["server.status_change", "player.count_spike"], "active": true}
Handle Retries & Idempotency
ServerPulse retries failed deliveries using exponential backoff up to 24 hours. Always return a 2xx status code and implement idempotency checks using the X-Request-Id header to avoid duplicate processing.