Webhooks

• A Discord webhook link. Events arrive as tidy embeds. You don’t need to write any code.
• Your own HTTPS endpoint. Events arrive as signed JSON.

​

Events

​

Payload

POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: ERA-Webhooks/1.0 (+https://apidocs.eraus.gg)
X-ERA-Timestamp: 1793875464
X-ERA-Signature: v1=5b0c3c9f8e0d7b...

{
  "server": { "id": "k3j9x0abq2mn", "name": "Sydney Metro RP" },
  "events": [
    {
      "id": 4182,
      "type": "player.kill",
      "timestamp": 1793875461,
      "data": {
        "victim": { "id": 2210934, "name": "reckless_ricky" },
        "killer": { "id": 1458291, "name": "jess_writes" }
      }
    },
    {
      "id": 4183,
      "type": "modcall.open",
      "timestamp": 1793875463,
      "data": { "caller": { "id": 98123, "name": "newplayer01" }, "callId": 12 }
    }
  ]
}

​

Event data

​

Verify the signature

signature = HMAC_SHA256(secret, timestamp + "." + raw_body)  as hex

import crypto from "node:crypto";

export function verify(rawBody, headers, secret) {
  const ts = headers["x-era-timestamp"];
  const sig = (headers["x-era-signature"] || "").replace(/^v1=/, "");
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

import hmac, hashlib, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-ERA-Timestamp", "")
    sig = headers.get("X-ERA-Signature", "").removeprefix("v1=")
    if not ts or abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

​

Delivery

• Reply with any 2xx within 5 seconds. Do the slow work after replying.
• A failed delivery is retried after about 5 seconds, 30 seconds, 2 minutes, then 10 minutes, then dropped. A 4xx reply other than 408 or 429 isn’t retried.
• Redirects aren’t followed.
• After 25 failures in a row the webhook is paused, so a dead endpoint isn’t hammered. The console shows it as paused. Saving the webhook again turns it back on.
• Events usually reach you within 3 to 10 seconds. They come in batches with each sync, not one request per event.
• If more than 200 batches are waiting, the oldest are dropped. The events feed still has everything from the last 7 days.

​

Rules for the URL

• Must be https:// on port 443, with no username or password in it.
• No IP addresses, localhost or internal hostnames, and no eraus.gg addresses.
• One webhook per server. Saving a new one replaces it. The URL is never shown back in the console, only its host name.