11. Webhooks
A webhook is an HTTPS POST the platform sends to your URL whenever your servers change. For a server deployment without MultiConnectSDK, it is how your backend learns a new container's address, and when to stop sending players to an old one.
Set it up
- Open your deployment from the dashboard: open your project, then the deployment.
- On the Webhooks panel, turn on Enable webhook, enter the Webhook URL, and click Save.
- Click Reveal secret and copy the signing secret. Store it as a secret, never in your repository.
- Click Send test event to check your endpoint. It sends a
webhook.testevent and shows what your endpoint answered. - Open Event reference to see the verification steps and a sample of every event.
The panel shows Healthy, or Failing with the number of failed deliveries in a row.
The URL must be https://, publicly reachable, and must not contain a username or password. Addresses that resolve to private or loopback ranges are refused.
Events
| Event | Sent when |
|---|---|
server.added |
A combined server became healthy. You can send players to it |
master.added |
A master became healthy, after a first deploy, redeploy, plan change or rollback |
worker.added |
A worker became healthy. Start assigning players to it |
worker.removed |
A worker is gone. Drop it from your rotation |
worker.migrated |
A worker came back on a different host, so its address changed. Replace the old entry |
master.migrated |
A master came back on a different host. Workers must use the new address |
generation.switched |
A new generation is live, after a redeploy, plan change or migration. containers is the new generation, and buildChanged says whether the build changed |
generation.retiring |
The most important event. Containers were given a retirement time. Stop sending new players to them now |
generation.retired |
The draining containers were removed and stopped billing |
container.unhealthy |
A container failed its health check. Route around it |
container.healthy |
A container passed its health check again |
deployment.stopped |
The deployment stopped. reason is CustomerRequested, ZeroBalance, BandwidthCeiling or DiskQuota |
deployment.started |
The deployment is serving again after a stop |
deployment.deleted |
The deployment was deleted and billing ended. Nothing follows it |
operation.failed |
An operation did not complete. rolledBack: true means the previous generation is still serving |
instance.ready |
An on-demand game server is running and healthy |
instance.removed |
On-demand game servers were removed. removedReason says why |
webhook.test |
Sent only by Send test event |
generation.retiring gives a reason: Superseded (a redeploy), ScaledDown, PlanChanged or Migrated.
Every event has the same envelope: event, deploymentId, deploymentName, occurredAt (ISO 8601 UTC) and data. Each container in data has containerId, regionId, region, roleId, role, ip, port, buildVersion, generation and retiresAt.
Script 11.1: A generation.retiring event (formatted for reading; the real body is one line)
{
"event": "generation.retiring",
"deploymentId": "10482",
"deploymentName": "my-game-servers",
"occurredAt": "2026-01-15T10:30:00.0000000Z",
"data": {
"retiresAt": "2026-01-15T11:30:00.0000000Z",
"reason": "Superseded",
"reasonId": 1,
"containers": [
{
"containerId": "Zr81bTq0LwE4",
"regionId": 1,
"region": "India",
"roleId": 2,
"role": "WorkerServer",
"ip": "203.0.113.7",
"port": 41180,
"buildVersion": 7,
"generation": 8,
"retiresAt": "2026-01-15T11:30:00.0000000Z"
}
]
}
}
Verify every delivery
Each delivery carries these headers: X-MC-Event (the event), X-MC-Delivery (a delivery id), X-MC-Timestamp, X-MC-Nonce and X-MC-Signature.
- Read the raw request body as bytes, before any JSON parsing.
- Build the string
{X-MC-Timestamp}:{X-MC-Nonce}:{rawBody}. - Compute HMAC-SHA256 over it with your webhook secret as the key, and hex-encode it in lower case.
- Compare it with
X-MC-Signatureusing a constant-time comparison. - Reject the request if
X-MC-Timestampis more than 5 minutes from your clock. - Treat
X-MC-Deliveryas an idempotency key: the same delivery can arrive twice.
Script 11.2: Verify a webhook in Node.js
const crypto = require("crypto");
function isValidWebhook(rawBody, headers, secret) {
const ts = headers["x-mc-timestamp"];
const nonce = headers["x-mc-nonce"];
const expected = crypto.createHmac("sha256", secret)
.update(`${ts}:${nonce}:${rawBody}`)
.digest("hex");
const given = headers["x-mc-signature"] || "";
const fresh = Math.abs(Date.now() - Date.parse(ts)) <= 5 * 60 * 1000;
return fresh && given.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
Delivery rules
- Answer 2xx as soon as you have stored the event, then do your work. Anything else is retried with backoff, 6 attempts over about 90 minutes, and then given up on.
- Order is not guaranteed. Use
occurredAt, not arrival order.

