Subscription Webhooks

1. The seven events

Subscribe with ["*"] and you receive all of them without changing anything. There is no subscription.amount_changed event — advertising an event before it can fire would let you subscribe to something that never arrives. A staged price change surfaces as a changed amount_usd on the next subscription.renewed.

All seven carry schema_version: "1.0".

2. The envelope

Every Invo delivery — subscription or otherwise — has the same outer shape. The event-specific fields are always inside data.

3. The shared subscription block

Five of the seven events — payment_failed, past_due, authentication_required, canceled and expired — open data with an identical block, so you can write one decoder and switch on event_type for the extras.

4. subscription.renewed — the authoritative grant

Fires once per settled cycle, inside the same transaction as the money — so there is no state in which the member was charged and you were not told, and none in which you were told about a charge that rolled back.

{
  "event_id": "8f3a...c1",
  "idempotency_key": "8f3a...c1",
  "event_type": "subscription.renewed",
  "schema_version": "1.0",
  "created_at": "2026-08-01T09:14:02.418913+00:00",
  "tenant_id": "97288428282",
  "data": {
    "subscription_id": "SUB_1786982400_A7K2M9QX",
    "item_id": "guild_membership_gold",
    "period_seq": 4,
    "transaction_id": "TXN_1786982400_K3P9",
    "order_id": 884213,
    "mint_order_id": 884212,
    "player_email": "member@example.com",
    "identity_id": "f3a1b8c0d4e5...",
    "amount_usd": "9.99",
    "amount_coins": "99.90",
    "period_start": "2026-07-01T09:00:00+00:00",
    "period_end": "2026-08-01T09:00:00+00:00",
    "current_period_start": "2026-08-01T09:00:00+00:00",
    "current_period_end": "2026-09-01T09:00:00+00:00",
    "next_charge_at": "2026-09-01T09:00:00+00:00",
    "funding": {
      "balance_applied_coins": "40.00",
      "card_charged_usd": "5.99",
      "minted_coins": "59.90",
      "new_balance": "0.00"
    },
    "split": {
      "total_usd": "9.99",
      "invo_fee_usd": "0.65",
      "partner_revenue_usd": "9.34",
      "invo_fee_coins": "6.50",
      "partner_revenue_coins": "93.40",
      "invo_fee_percent": "6.50"
    },
    "revenue_share_attribution": {
      "recipient_player_id": 40219,
      "percent": "10.00",
      "base_usd": "9.34",
      "attributed_amount_usd": "0.93",
      "settled_by_invo": false
    },
    "metadata": { "guild_id": "g_8812" }
  }
}

Fields

5. Dunning: payment_failed, past_due, expired

A failed renewal is retried on a schedule; the default is 3 retries over 7 days, then the subscription expires. The member keeps access for the whole grace window — only subscription.expired takes it away.

subscription.payment_failed

Fires on the first failing attempt, while the member still has access and can still fix their card — that is the entire point of a grace window. It fires on subsequent failures too; first_failure tells them apart, so you can escalate your messaging as the deadline approaches, or filter on it and only mail once.

{
  "event_type": "subscription.payment_failed",
  "schema_version": "1.0",
  "data": {
    // ...the shared subscription block (section 3)...
    "status": "past_due",
    "attempt_no": 1,
    "period_seq": 5,
    "period_start": "2026-08-01T09:00:00+00:00",
    "period_end": "2026-09-01T09:00:00+00:00",
    "amount_due_usd": "9.99",
    "outcome": "failed",
    "reason": "card_declined",
    "failure_code": "card_declined",
    "failure_message": "Your card was declined.",
    "first_failure": true,
    "retry_at": "2026-08-03T09:00:00+00:00",
    "retries_remaining": 3,
    "grace_period_end": "2026-08-08T09:00:00+00:00",
    "access_retained": true
  }
}

subscription.past_due

The state transition, not the attempt. Fires once, when the subscription actually enters past_due. Subscribe to this one if you want "tell me when a member goes into arrears" and want to ignore the per-attempt noise. Extras: period_seq, amount_due_usd, grace_period_end, retry_at, retries_remaining, and access_retained: true. Soft-degrade here; keep the row.

subscription.expired

The retry budget is exhausted. This is the event that revokes.

{
  "event_type": "subscription.expired",
  "schema_version": "1.0",
  "data": {
    // ...the shared subscription block (section 3)...
    "status": "expired",
    "period_seq": 5,
    "failed_period_start": "2026-08-01T09:00:00+00:00",
    "failed_period_end": "2026-09-01T09:00:00+00:00",
    "final_attempt_no": 4,
    "attempts_used": 4,
    "failure_code": "card_declined",
    "failure_message": "Your card was declined.",
    "ended_at": "2026-08-08T09:03:11+00:00",
    "final_period_end": "2026-08-01T09:00:00+00:00",
    "access_retained": false
  }
}

6. authentication_required, canceled, refunded

subscription.authentication_required — the one that will surprise you

{
  "event_type": "subscription.authentication_required",
  "schema_version": "1.0",
  "data": {
    // ...the shared subscription block (section 3)...
    "status": "awaiting_authentication",
    "period_seq": 6,
    "attempt_no": 1,
    "period_start": "2026-09-01T09:00:00+00:00",
    "period_end": "2026-10-01T09:00:00+00:00",
    "amount_due_usd": "9.99",
    "card_amount_usd": "5.99",
    "confirmation_url": "https://invo.network/subscription-auth?token=<opaque>",
    "expires_at": "2026-09-04T09:00:00+00:00",
    "reason": "authentication_required",
    "access_retained": true,
    "retry_consumed": false
  }
}

subscription.canceled

Fires when the cancellation is requested, in both modes. An at-period-end cancel is one event with a future effective date — not a promise followed by a second event when the date arrives. Nothing else is coming; schedule the revocation yourself.

{
  "event_type": "subscription.canceled",
  "schema_version": "1.0",
  "data": {
    // ...the shared subscription block (section 3)...
    "status": "active",
    "cancel_at_period_end": true,
    "effective_at": "2026-09-01T09:00:00+00:00",
    "canceled_at": "2026-08-14T16:02:44+00:00",
    "ended_at": null,
    "access_until": "2026-09-01T09:00:00+00:00",
    "paid_through": "2026-09-01T09:00:00+00:00",
    "reason": "member_request"
  }
}

subscription.refunded

You called the refund endpoint on a billed cycle. Fires per refund, so a cycle refunded in instalments produces one event each time. Reverse entitlement for the refunded period, and — importantly — take the recipient accrual back off your books using the corrected attribution figure.

{
  "event_type": "subscription.refunded",
  "schema_version": "1.0",
  "data": {
    "subscription_id": "SUB_1786982400_A7K2M9QX",
    "item_id": "guild_membership_gold",
    "period_seq": 4,
    "transaction_id": "TXN_1786985511_B4W1",
    "client_request_id": "refund-2026-08-14-0007",
    "player_email": "member@example.com",
    "identity_id": "f3a1b8c0d4e5...",
    "amount_usd": "3.00",
    "total_refunded_amount_usd": "3.00",
    "period_amount_usd": "9.99",
    "is_full_refund": false,
    "reason": "goodwill",
    "period_status": "paid",
    "refund": {
      "funding_shape": "mixed",
      "balance_delta_coins": "30.00",
      "card_refunded_usd": "0.00",
      "new_balance": "30.00",
      "invo_fee_retained": true,
      "partner_revenue_reversed_usd": "2.81",
      "partner_revenue_reversal_mode": "prorata"
    },
    "revenue_share_attribution": {
      "recipient_player_id": 40219,
      "percent": "10.00",
      "original_attributed_amount_usd": "0.93",
      "refunded_attributed_amount_usd": "0.28",
      "net_attributed_amount_usd": "0.65",
      "settled_by_invo": false
    },
    "metadata": { "guild_id": "g_8812" }
  }
}

7. Ordering, duplicates and idempotency

The caveats worth writing down

• A card-funded renewal also emits purchase.completed. Coins really were minted, through the same credit path every top-up uses, so the event is honest rather than spurious. If your purchase.completed handler grants something, it will now grant on renewals too. Correlate: the order_id on that purchase.completed is the same id as mint_order_id on the paired subscription.renewed. A wallet-funded renewal emits only subscription.renewed.
• Cancellation fires once, at request time. There is no event when effective_at arrives. Schedule your own revocation from access_until.
• Entitlement always derives from paid cycles. On renewed that is period_end; on canceled it is access_until; on expired it is final_period_end. It is never current_period_end, which is a projection that exists before any money has moved.
• Pick the right business key per event. (subscription_id, period_seq) identifies one paid cycle and is correct for renewed. It is not unique for refunded — one cycle can be refunded several times — so key that on the refund transaction_id.
• Return 2xx quickly. Do the durable write, ACK, and do slow work (email, push) off a queue. A non-2xx is a request to retry; only send one for an error a retry could actually fix.

A worked handler

// Signature verification is identical for every Invo event; see /docs/webhooks
// for verifyInvoSignature(). This file is only about what to DO with the event.

app.post('/invo/webhooks',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    if (!verifyInvoSignature(req.body, req.get('X-Invo-Signature'),
                             process.env.INVO_WEBHOOK_SECRET)) {
      return res.status(400).send('bad signature');
    }
    const event = JSON.parse(req.body.toString('utf8'));

    // LAYER 1 — transport de-dupe. Stable across retries AND manual replays.
    if (await claimDeliveryKey(req.get('X-Invo-Idempotency-Key'))) {
      return res.status(200).send('duplicate');
    }

    try {
      await handleSubscriptionEvent(event);
    } catch (err) {
      // Non-2xx tells Invo to retry with backoff. Only do this for errors a
      // retry can actually fix (your DB was down) — not for a bad payload.
      logger.error(err);
      return res.status(500).send('retry me');
    }
    return res.status(200).send('ok');
  });

async function handleSubscriptionEvent(event) {
  const d = event.data;

  switch (event.event_type) {

    case 'subscription.renewed': {
      // LAYER 2 — business idempotency. One paid cycle is exactly
      // (subscription_id, period_seq). Re-running this must be a no-op, not a
      // second month of access and not a second accrual.
      const cycleKey = d.subscription_id + ':' + d.period_seq;

      await grantEntitlement({
        cycleKey,
        subscriptionId: d.subscription_id,
        itemId:         d.item_id,
        member:         d.identity_id,
        // period_end is what THIS renewal paid for. current_period_end is the
        // next, unpaid cycle — granting to it gives away a free month.
        accessUntil:    d.period_end,
        nextChargeAt:   d.next_charge_at,
      });

      // Accrue what you owe the recipient. Invo has paid them NOTHING:
      // settled_by_invo is false. You pay them, out of your own settlement.
      if (d.revenue_share_attribution) {
        await accrueAttribution({
          cycleKey,
          recipientPlayerId: d.revenue_share_attribution.recipient_player_id,
          amountUsd:         d.revenue_share_attribution.attributed_amount_usd,
        });
      }
      return;
    }

    case 'subscription.payment_failed':
      // access_retained is TRUE. Do not revoke. Mail them the deadline.
      if (d.first_failure) {
        await emailFixYourCard({
          member:   d.identity_id,
          amount:   d.amount_due_usd,
          deadline: d.grace_period_end,   // may be null — send without a date
          retryAt:  d.retry_at,
        });
      }
      return;

    case 'subscription.authentication_required':
      // NOT a failure. No retry consumed, access retained. The member must open
      // this link before expires_at or they will be expired for nothing.
      if (d.confirmation_url) {
        await sendAuthChallenge({
          member:    d.identity_id,
          url:       d.confirmation_url,   // never construct this yourself
          amountUsd: d.card_amount_usd,    // the CARD amount, not the price
          expiresAt: d.expires_at,
        });
      }
      return;

    case 'subscription.past_due':
      await softDegrade(d.subscription_id);   // keep the row, dim the perks
      return;

    case 'subscription.canceled':
      // Fires at REQUEST time. There is no second event on the effective date —
      // schedule the revocation yourself.
      await scheduleRevocation({
        subscriptionId: d.subscription_id,
        at:             d.access_until,      // paid-through, may be ~now
        immediate:      !d.cancel_at_period_end,
      });
      return;

    case 'subscription.expired':
      // The event that actually revokes.
      await revokeEntitlement({
        subscriptionId: d.subscription_id,
        paidThrough:    d.final_period_end,  // null = never successfully charged
      });
      return;

    case 'subscription.refunded': {
      // NOT keyed on period_seq — a cycle can be refunded several times.
      // The refund transaction id is unique per refund event.
      await reverseCycle({
        refundKey:      d.transaction_id,
        subscriptionId: d.subscription_id,
        periodSeq:      d.period_seq,
        amountUsd:      d.amount_usd,        // THIS refund only
        fullyRefunded:  d.period_status === 'refunded',
      });
      if (d.revenue_share_attribution) {
        await setAttributionNet({
          cycleKey:  d.subscription_id + ':' + d.period_seq,
          amountUsd: d.revenue_share_attribution.net_attributed_amount_usd,
        });
      }
      return;
    }

    default:
      // Log the FULL raw envelope for anything you don't handle yet, BEFORE you
      // ACK — a 2xx means "don't retry", and the event is gone otherwise.
      await logUnhandled(event);
  }
}

8. Troubleshooting

9. Receiver checklist

• Subscribe with ["*"] so a new subscription event never silently misses you.
• Grant and extend access ONLY on subscription.renewed — never on an API response.
• Grant to period_end. Never to current_period_end.
• Revoke on subscription.expired, and at access_until for a cancellation you scheduled yourself.
• Treat subscription.authentication_required as an action item, not a failure — surface confirmation_url before expires_at.
• Do not revoke on payment_failed or past_due; access_retained is true.
• De-dupe on X-Invo-Idempotency-Key, then key your writes on (subscription_id, period_seq) — and on the refund transaction_id for refunds.
• Expect purchase.completed alongside card-funded renewals; correlate on mint_order_id.
• Parse every money field as an exact decimal, never a float; never compare a *_coins figure against a *_usd one.
• Log the full raw envelope for any event you do not handle yet, before you ACK.

Related

• Subscriptions Overview — the model, the billing clock, and who owns what.
• Create a Subscription — subscribing, idempotency, and capturing a card.
• Manage a Subscription — cancel, price changes, refunds.
• Renewals & Dunning — how a renewal is funded, retried and recovered.
• Subscription Reporting & Attribution — aggregate the per-renewal attribution into a payout run.
• Webhooks — signatures, headers, retries, secret rotation.
• Webhook Management — delivery history and replaying a dropped event.