Saltar al contenido
ZokoGames

Iniciar sesión

Esta página aún no está traducida y se muestra en inglés.

Webhooks

En esta página

Webhooks

A webhook makes our servers send a signed POST request to your server when something changes in your studio. Use it to post to a chat channel, start your own pipeline when a build goes live, or keep an internal dashboard in step, instead of polling the console.

Webhooks belong to the studio, not to one game. Owners and admins manage them on the Webhooks page of the developer console.

Set one up#

  1. Open Webhooks in the console and choose Add an endpoint.
  2. Enter an https:// address, an optional description and the events you want.
  3. Copy the signing secret (it starts with whsec_). It is shown once. If you lose it, use Rotate secret; the old one stops working at once.
  4. Press Send test. A ping event is delivered immediately and the result (HTTP status or error) is shown.

A studio can have up to 5 endpoints. You can pause and resume an endpoint without losing it. The console keeps the 50 most recent delivery results for the studio, with time, event, status and duration.

Events#

Event Sent when data fields
review.outcome A reviewer approved, rejected or asked for changes. gameId, gameSlug, gameName, outcome, note, rejectionReasons (list)
build.published A new build passed validation and was published. gameId, gameSlug, buildId, version, totalBytes, fileCount
build.activated A build became the live version, including a rollback. gameId, gameSlug, buildId, version, previousBuildId
feedback.replied Someone on your team replied to player feedback. gameId, feedbackId, subject, emailed, resolved
leaderboard.reset Leaderboard scores were reset. gameId, gameSlug, scope, season, deleted (rows removed)
ping You pressed Send test. Cannot be subscribed to. message, studio

The request#

POST /hooks/zoko HTTP/1.1
Content-Type: application/json
User-Agent: ZokoGames-Webhooks/1
X-Zoko-Event: build.published
X-Zoko-Delivery: 6f1c2d1e-8a54-4e0b-9a39-0f4c9a5b7d10
X-Zoko-Signature: t=1763424000,v1=5b1f...c9
{
  "id": "6f1c2d1e-8a54-4e0b-9a39-0f4c9a5b7d10",
  "event": "build.published",
  "createdAt": "2026-11-18T00:00:00.000Z",
  "studioId": "…",
  "data": { "gameId": "…", "gameSlug": "my-game", "buildId": "…", "version": "1.2.0", "totalBytes": 18400000, "fileCount": 212 }
}

id is the same as the X-Zoko-Delivery header and is unique per delivery.

Verify the signature#

Anyone who learns your URL can post to it, so check every request. The X-Zoko-Signature header has two parts:

  • t: the time we signed, in Unix seconds.
  • v1: the lowercase hex HMAC-SHA256 of the text "<t>.<raw body>", keyed with your endpoint secret (the whole whsec_... string).

Steps: read the raw request body before any JSON parsing, build t + "." + body, compute the HMAC, compare it to v1 in constant time, and reject a t that is more than five minutes from your clock to stop replays.

import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const SECRET = process.env.ZOKO_WEBHOOK_SECRET;
const app = express();

app.post("/hooks/zoko", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("x-zoko-signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);

  const expected = createHmac("sha256", SECRET).update(`${t}.`).update(req.body).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "hex");
  const want = Buffer.from(expected, "hex");
  if (given.length !== want.length || !timingSafeEqual(given, want)) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // de-duplicate on event.id, then handle event.event
  res.sendStatus(204);
});
import hashlib, hmac, os, time
from flask import Flask, request, abort

SECRET = os.environ["ZOKO_WEBHOOK_SECRET"].encode()
app = Flask(__name__)

@app.post("/hooks/zoko")
def zoko_hook():
    header = request.headers.get("X-Zoko-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        abort(400)
    if abs(time.time() - t) > 300:
        abort(400)

    body = request.get_data()  # raw bytes, before any JSON parsing
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(401)

    event = request.get_json()
    # de-duplicate on event["id"], then handle event["event"]
    return "", 204

Delivery, retries and timeouts#

  • We make one attempt per delivery. There are no automatic retries: a failure is only recorded in the delivery log.
  • Your server must answer with a 2xx status within 5 seconds. Anything else, including a timeout, counts as failed. Do the real work after you respond.
  • Redirects are not followed. Answer on the exact URL you registered.
  • Deliveries are sent after the action that triggered them finishes, and a broken endpoint never blocks that action.
  • Order is not guaranteed. Use createdAt and id, and de-duplicate on id.

Because nothing is retried, treat webhooks as a convenience and reconcile from the console or your own checks when a failure shows in the log.

Which addresses are accepted#

To protect everyone, endpoints must be reachable on the public internet:

  • https only, on the default port 443, with no username or password in the URL.
  • No localhost, .local, .internal or single-label host names.
  • The host name must resolve, and every address it resolves to must be public. Private, loopback, link-local, carrier-grade NAT and multicast ranges are refused.
  • The check runs again before each delivery, so a name that later points at a private address stops receiving events.

For local development, expose your dev server through a public HTTPS tunnel.

Troubleshooting#

Log shows Meaning
Timed out after 5 seconds Respond first, work later.
A 3xx status Redirects are not followed; register the final URL.
4xx / 5xx Your server refused or failed; check the signature code and the raw-body handling.
The address must be reachable on the public internet. The host resolves to a private address.
That host name does not resolve. DNS has no answer yet.

Signature mismatches almost always come from parsing and re-serialising the JSON before hashing. Hash the exact bytes you received.

Purchases have no webhook; verify the purchase token instead.

¿Algo poco claro, incorrecto o que falta en esta página? Cuéntanoslo a través de soporte · Prueba tu juego en la herramienta de vista previa

Ajustes de cookies

Elige qué cookies puede usar ZokoGames. Las cookies necesarias están siempre activas porque el sitio no puede funcionar sin ellas.

  • Inicio de sesión, idioma y estas opciones. Siempre activas.

  • Recuerda cosas como tus juegos jugados recientemente en este dispositivo.

  • Cuenta partidas y visitas con un identificador de visitante aleatorio para ayudarnos a mejorar.

  • Permite anuncios personalizados, que financian los juegos gratuitos.