Webhooks
Na této stránce
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#
- Open Webhooks in the console and choose Add an endpoint.
- Enter an
https://address, an optional description and the events you want. - 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. - Press Send test. A
pingevent 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 wholewhsec_...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 "", 204Delivery, 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
2xxstatus 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
createdAtandid, and de-duplicate onid.
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:
httpsonly, on the default port 443, with no username or password in the URL.- No
localhost,.local,.internalor 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.