MultiConnectMultiConnectDocs Website home
MultiConnectCloud › Server Deployments

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

  1. Open your deployment from the dashboard: open your project, then the deployment.
  2. On the Webhooks panel, turn on Enable webhook, enter the Webhook URL, and click Save.
  3. Click Reveal secret and copy the signing secret. Store it as a secret, never in your repository.
  4. Click Send test event to check your endpoint. It sends a webhook.test event and shows what your endpoint answered.
  5. 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.

  1. Read the raw request body as bytes, before any JSON parsing.
  2. Build the string {X-MC-Timestamp}:{X-MC-Nonce}:{rawBody}.
  3. Compute HMAC-SHA256 over it with your webhook secret as the key, and hex-encode it in lower case.
  4. Compare it with X-MC-Signature using a constant-time comparison.
  5. Reject the request if X-MC-Timestamp is more than 5 minutes from your clock.
  6. Treat X-MC-Delivery as 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