Webhooks

Overview

Webhooks deliver platform events (builds, analytics events and your game’s own events) to your backend via HTTP POST. Your server must respond within 10 seconds; a failed delivery is retried for about 24 hours.

Create a webhook endpoint

Developer Portal → Webhooks → pick the game → Add Webhook

Field	Notes
URL	Your HTTPS endpoint — must be publicly reachable
Secret	Used to sign requests — store securely, never commit. Leave it empty and one is generated
Events	Select which events to receive — at least one
Security headers	Optional: up to 10 custom headers sent with every delivery

Available events

Event	Triggered when
`BUILD_RECEIVED`	Build processed: waiting for review (`status: "pending_review"`), or ready to test for a private game (`status: "ready"`)
`BUILD_FAILED`	Build processing failed; the payload carries `failure.code` and `failure.message`
`BUILD_LIVE`	Build reviewed and set live
`BUILD_REJECTED`	Build failed review
`BUILD_DEPRECATED`	Build replaced by a newer live version
`BUILD_PRUNED`	Old build removed by retention, with its files
`SDK_ANALYTICS_EVENT`	Player analytics event fired
`CUSTOM_WEBHOOK_EVENT`	Event your game sent via `SusaPlaySDK.Webhooks.SendEvent`

Any other event name is silently dropped when you save the subscription — check the saved list in the portal to confirm what was accepted. A list with no valid event is refused.

Body

Every delivery is a JSON object with the event at the top level and the event’s own fields under data:

{
  "eventId": "9f2c4a1e8b7d4c6fa1e05b3d2c8f7a60",
  "event": "BUILD_LIVE",
  "gameId": "your-game-id",
  "timestamp": "2026-07-20T14:30:00Z",
  "data": { "versionId": "1.4.2", "platform": "webgl" }
}

Verify signatures

Every request carries these headers:

Header	Contents
`X-Platform-Signature`	HMAC-SHA256 of the raw body, hex-encoded, keyed with your webhook secret
`X-Platform-Event`	The event name, so you can route without parsing first
`X-SusaPlay-Delivery-Attempt`	Which attempt this is, `1` to `10`

Always verify the signature before processing.

import crypto from 'crypto'

function verifySignature(req, secret) {
  const signature = req.headers['x-platform-signature']
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body) // raw body string, not parsed JSON
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  res.sendStatus(200)            // respond fast
  processAsync(req.body.toString()) // heavy work after
})

Parse the raw body for signature verification — never verify against a pre-parsed JSON object.

Reliability rules

Return 2xx within 10 seconds. Any other status (4xx included), a timeout or a connection error is a failed delivery.
Failed deliveries are retried for about 24 hours, 10 attempts in all: after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 8 h and 8 h. Every attempt sends the same body and the same eventId. After the tenth, the delivery is dropped, so if a piece of state must be correct, reconcile it against the API rather than relying on having received an event.
Deliveries are not ordered. A retried event can arrive after events that happened later.
Pending retries follow your settings. A changed URL or rotated secret applies from the next attempt; a deleted or paused webhook gets no further attempts. An event your subscription leaves out is never sent, so it is never retried either.
Deduplicate on eventId. Every delivery carries an eventId at the top level of the body. It identifies the occurrence, not the delivery: one event sent to three of your endpoints carries the same eventId to all three, a retry carries the same one again, and two separate occurrences never share one. Record the ids you have processed and ignore a repeat.
Be idempotent anyway. Respond fast, queue the work, and make replays harmless.
Cap your endpoints. A game can have at most 20 webhooks.

Secrets

The signing secret is shown once, when you create the webhook. It cannot be read back afterwards — the portal only shows its last four characters. Store it in your own secret manager at creation time. If you lose it, or want to rotate it, create a new webhook with a new secret, update your endpoint, then delete the old webhook.

Test a webhook

Developer Portal → Webhooks → click Test on the webhook. SusaPlay sends one test delivery; check your server’s logs for it. The portal shows only when the webhook last fired — there is no delivery log.

Getting Started

Integration

SDK

API

Overview

Create a webhook endpoint

Available events

Body

Verify signatures

Reliability rules

Secrets

Test a webhook

​Overview

​Create a webhook endpoint

​Available events

​Body

​Verify signatures

​Reliability rules

​Secrets

​Test a webhook

Overview

Create a webhook endpoint

Available events

Body

Verify signatures

Reliability rules

Secrets

Test a webhook