Webhooks

# Register or update your endpoint + the events you subscribe to.
# RECOMMENDED: use ["*"] to receive every event type, then filter server-side.
# If you subscribe to a SUBSET, you MUST include "transfer.claim_pending" to be
# told an inbound transfer/send is awaiting your player's claim (the #1 gap:
# without it, your app never learns there's something "to collect").
curl -X PUT https://api.invo.network/api/dev/webhooks/games/<GAME_ID> \
  -H "X-Game-Secret-Key: ivsdk_<your_sdk_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-server.com/invo/webhooks",
    "subscribed_events": ["*"]
  }'

# Response: signing_secret is returned ONCE, on first creation. Save it now;
# POST .../rotate-secret later to roll it.
# {
#   "success": true,
#   "created": true,
#   "signing_secret": "<long-random-string>",   // store this securely
#   "subscription": { ... }
# }

{
  "event_id": "f3a1c9d2-...-b7",         // per-delivery id: same on retries, new on a replay
  "idempotency_key": "f3a1c9d2-...-b7",  // stable logical id; DEDUPE ON THIS
  "event_type": "purchase.completed",
  "schema_version": "1.0",
  "created_at": "2026-06-05T12:34:56.000000+00:00",
  "tenant_id": "123",                    // your game_id
  "data": {
    "transaction_id": "TXN...",
    "order_id": "ORD_...",
    "player_email": "player@example.com",
    "identity_id": "f3a1b8c0d4e5...",
    "usd_amount": "10.00",
    "currency_amount": "1000",
    "currency_name": "GOLD",
    "new_balance": "4200",
    "rail": "platform",           // settlement rail, provider-neutral; a Steam-channel
                                  // purchase carries "steam" here too (rail follows channel)
    "channel": "web",             // storefront: steam | ios | android | web | console
                                  // null = legacy game key ("unattributed", a real answer)
    "metadata": { "my_player_id": "p_123" }   // YOUR metadata from the purchase call, echoed verbatim
    // ...event-specific fields per event_type
  }
}

const crypto = require('crypto');
const express = require('express');
const app = express();

// IMPORTANT: capture the RAW body; the signature is over the exact bytes.
app.post('/invo/webhooks',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    if (!verifyInvoSignature(req.body, req.get('X-Invo-Signature'), process.env.INVO_WEBHOOK_SECRET)) {
      // Any non-2xx makes INVO retry this delivery. That is what you want: a forged
      // request is not INVO's, so nothing retries it, and a genuine delivery that
      // fails verification (for example a secret you have not rotated yet) is
      // retried until your secret is right, instead of being lost.
      return res.status(400).send('bad signature');
    }
    const event = JSON.parse(req.body.toString('utf8'));

    // De-dupe on the stable idempotency key (survives retries + replays).
    if (alreadyProcessed(req.get('X-Invo-Idempotency-Key'))) {
      return res.status(200).send('duplicate');
    }

    // IMPORTANT: log the FULL raw envelope for ANY event you don't yet handle:
    // before you ACK. A 2xx tells Invo "received, don't retry", so an event your
    // handler doesn't recognize yet (deployed after it fired, or a type you don't
    // map) is GONE unless you logged it. Logging only event_type is the #1 way
    // teams silently lose an inbound "money arrived" event. Keep the raw body.
    if (!isHandled(event.event_type)) {
      logUnhandledWebhook({
        event_id: event.event_id,
        idempotency_key: req.get('X-Invo-Idempotency-Key'),
        event_type: event.event_type,
        raw: req.body.toString('utf8'),   // full payload, recoverable/replayable
      });
      return res.status(200).send('ok (logged unhandled)');
    }

    handle(event);            // do your work (ideally async; see section 6)
    return res.status(200).send('ok');   // 2xx = we won't retry
  });

function verifyInvoSignature(rawBody, header, secret, toleranceSec = 300) {
  if (!header || !secret) return false;
  const t = header.split(',').find(p => p.trim().startsWith('t='))?.split('=')[1];
  const sigs = header.split(',').filter(p => p.trim().startsWith('v1='))
                     .map(p => p.split('=')[1].trim());
  if (!t || sigs.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSec) return false; // replay guard
  const expected = crypto.createHmac('sha256', secret)
                         .update(Buffer.concat([Buffer.from(t + '.'), rawBody]))
                         .digest('hex');
  return sigs.some(s =>
    s.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}