REST API & webhooks

One API behind everything: the inbox, Telegram, Discord, the MCP server and the CLI are all clients of it.

Basics

• Base URL: https://app.inngame.app/v1 (the previous https://inngame.meffysto.workers.dev/v1 keeps working)
• Auth: Authorization: Bearer ig_sk_… (an API key). The key determines the organization.
• Format: JSON in and out. Timestamps are Unix milliseconds. IDs are prefixed strings (cnv_…, msg_…, eu_… for players, bug_…).
• Errors: a non-2xx status with {"error": "code", "message": "…"}. Common codes: invalid_api_key (401), requires_reply / requires_admin (403), human_approval_required (403), conversation_not_found (404).
• Scopes: read < reply < all. In the tables below, all means admin rights. Every write is recorded in the audit log.
• Rate limits: 300 requests a minute per API key; for players, 20 messages or uploads and 60 events a minute. Over the limit you get 429 rate_limited: wait a minute and retry.
• Pagination: lists return up to 50 items (100 max with limit) and a cursor: pass nextBefore as before for conversations, or the oldest seq as before for messages.

curl "https://app.inngame.app/v1/conversations?status=open&unread=1" \
  -H "Authorization: Bearer $INNGAME_API_KEY"

Conversations and messages

Cards

Add a card to a message to show a button in the chat:

{
  "body": "Sorry about that! Here's a little something.",
  "card": {
    "kind": "item",                 // review | offer | link | screen | item | refund | restore
    "label": "Claim",
    "item": { "id": "gems_500", "name": "500 gems", "quantity": 1 }
  }
}

Other fields: url (link, review fallback), screen and value (screen), offerId (offer). An item card can be claimed once; you get an item.claimed webhook to grant it on your server.

Leave out label on review and refund cards to show the SDK's own text in the player's language (“Leave a review”, “Request a refund”). Cards Inngame sends itself carry the English default plus "defaultLabel": true; SDK 0.2.2 and later replace it with the translated text.

Players

Apps, organization and keys

Bugs

The same bugs as the Bugs page of the inbox. Every bug has a url to that page, which your teammates can open from Telegram, Discord, the weekly digest or an agent's summary.

Refunds

FAQ and automations

An automation has a triggerEvent (a game event or a subscription event such as trial_started, subscription_cancelled, billing_issue), a frequency, an audience (rules on player metadata), a delay (now, minutes or local_time) and actions: message, card (offer, link, screen, item), review, open_chat, wait.

SDK endpoints

The SDKs call /v1/sdk/* with the public app key in X-App-Key and a device token as bearer. Use them directly only if you're writing your own client (a web game, another engine).

Webhooks

Webhooks send events to your server: grant claimed items, log refunds, page someone on a bug spike. Manage them in the inbox (Settings → Webhooks) or with the API, signed in as an admin. Agent keys can't create or read webhooks, even with scope all: a webhook can send every message to any URL, so a person sets it up.

Each delivery is a POST with a JSON body, a user-agent of Inngame-Webhooks/1 and an inngame-signature header. Respond with a 2xx within 8 seconds. Failed deliveries (network errors, timeouts, 408, 429 and 5xx) are retried after about 1 and 5 minutes, then 30 minutes, 2, 6 and 12 hours: seven attempts over about a day. Another 4xx is taken as a refusal and not retried. Retries keep the same event id, so make your handler idempotent. The last result is on the webhook (last_status, last_error, pending retries). POST /webhooks/:id/test pings that webhook only.

{
  "id": "evt_8sd7f6g5h4j3k2l1m0n9",
  "type": "item.claimed",
  "created": 1793452800000,
  "appId": "app_...",
  "data": {
    "messageId": "msg_...",
    "conversationId": "cnv_...",
    "player": { "id": "eu_...", "externalId": "player-1842", "steamId": null },
    "card": { "kind": "item", "label": "Claim", "item": { "id": "gems_500", "name": "500 gems", "quantity": 1 }, "claimedAt": 1793452800000 },
    "action": "claimed"
  }
}

Event list

Verifying signatures

The header looks like this:

inngame-signature: t=1793452800,v1=pZ3f…Kq8

• t is the Unix time in seconds when the event was sent.
• v1 is the HMAC-SHA256 of the string t + "." + raw body, keyed with your webhook secret, encoded as base64url (no padding).
• Compute it over the raw request body, before any JSON parsing. Compare in constant time, and reject events whose t is more than 5 minutes old.

// Node.js (Express)
import crypto from "node:crypto";

app.post("/inngame-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("inngame-signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  const body = req.body.toString("utf8");
  const expected = crypto
    .createHmac("sha256", process.env.INNGAME_WEBHOOK_SECRET)
    .update(`${t}.${body}`)
    .digest("base64url");
  const ok =
    parts.v1 &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected)) &&
    Math.abs(Date.now() / 1000 - t) < 300;
  if (!ok) return res.status(400).send("bad signature");

  const event = JSON.parse(body);
  if (event.type === "item.claimed") grantItem(event.data.player, event.data.card.item);
  res.sendStatus(200);
});

# Python
import base64, hashlib, hmac, time

def verify(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = parts.get("t", "")
    mac = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).digest()
    expected = base64.urlsafe_b64encode(mac).rstrip(b"=").decode()
    return hmac.compare_digest(parts.get("v1", ""), expected) and abs(time.time() - int(t)) < 300