Overview

The Pending Actions webhook lets your platform know what investment actions a Gateway user still has outstanding on their invested smallcases — without you having to poll for them.

On a recurring schedule, smallcase Gateway computes, for every Gateway user, the set of pending actions across all their invested smallcases and delivers them as a single push to your configured postback URL. You can use this to power reminders and nudges on your end — for example "1 smallcase needs a rebalance", "complete your pending Fix", "your scheduled Invest More is due", or "your subscription has lapsed".

smallcase Gateway sends a POST request with a JSON payload to your registered pending-actions postback URL. The eventType on every payload is USER.PENDING_ACTIONS.

There are four kinds of pending action, and a single user's payload can carry any combination of them:

Delivery model

• Cadence — the webhook is produced by a scheduled batch job that runs periodically. Each run recomputes pending actions for all eligible users and pushes them out.
• One payload per user — each user with at least one pending action gets one POST, containing all their pending actions grouped by invested smallcase (data.investments[]).
• Grouping — actions are grouped under the invested smallcase they belong to. An invested smallcase entry only includes the action keys that are actually pending for it.
• Identity — the user is identified by data.smallcaseAuthId, matching the value returned to you during login/connect.

Consuming the webhook

1. Create a public HTTPS endpoint on your backend that accepts a POST with a JSON body, and returns any 2xx to acknowledge receipt (respond within a 10-second timeout).
2. Share the endpoint URL with your smallcase Gateway integration contact so it can be registered as your pending-actions postback URL.

Until a URL is on file, this webhook stays silent — nothing is queued.

Payload structure

{
  "timestamp": "2026-08-20T07:33:48.459Z",
  "checksum": "3c9addb8060b846c911ad8477ea0bf4a1af995a02aff8cc2453f138cc5271562",
  "eventType": "USER.PENDING_ACTIONS",
  "data": {
    "smallcaseAuthId": "5ef33705f610f80b5453b319",
    "investments": [
      {
        "iscid": "68b965f4395b3ab21390e106",
        "smallcaseName": "Top 100 Stocks - Quant Tracker",
        "scid": "SCET_0004",
        "rebalanceAction": {
          "date": "2026-04-16T00:00:00.000Z",
          "label": "Quarterly Update: Weights Change",
          "rationale": "To ensure optimal exposure, the weighting scheme has been updated by Windmill Capital"
        },
        "investMoreAction": {
          "source": "PROFESSIONAL",
          "scheduledDate": "2026-08-11T00:00:00.000Z",
          "frequency": "1m"
        }
      },
      {
        "iscid": "69ca6e399c4346b87e38ba3d",
        "smallcaseName": "Gateway | Liquid Stock",
        "scid": "GATEMO_0005",
        "fixAction": {
          "date": "2026-03-25T14:43:19.281Z",
          "filled": 1,
          "quantity": 2,
          "originalLabel": "BUY"
        }
      },
      {
        "iscid": "69ca91689c4346b87e38c06b",
        "smallcaseName": "Gateway | Liquid ETF + Stocks",
        "scid": "GATEMO_0004",
        "subscriptionAction": {
          "scid": "GATEMO_0004",
          "status": "UNSUBSCRIBED",
          "unsubscribeDate": "2026-07-06T00:00:00.000Z",
          "reason": "Payment processing failed",
          "userPlanId": "69ca8fe0e8c390563c0ba5a1"
        }
      }
    ]
  }
}

Top-level fields

investments[] entry

Action types

Fix

A Fix signals that the user's holdings for this smallcase have drifted from the intended composition and need a corrective set of orders (for example, after a partially-filled or failed order, or a manage/exit flow). Surface it as a "complete your pending order / fix your smallcase" nudge.

{
  "date": "2026-03-25T14:43:19.281Z",
  "filled": 1,
  "quantity": 2,
  "originalLabel": "BUY"
}

Rebalance

A Rebalance means the smallcase manager has published an update to the smallcase (weights and/or constituents changed) and the user should rebalance their holding to stay aligned with the latest version.

{
  "date": "2026-04-16T00:00:00.000Z",
  "label": "Quarterly Update: Weights Change",
  "rationale": "To ensure optimal exposure, the weighting scheme has been updated by Windmill Capital"
}

Invest More

An Invest More action is a scheduled reminder for the user to invest more into the smallcase as part of a recurring plan. (This replaces the older manual-SIP reminders.) Use frequency and scheduledDate to show when the next contribution is due.

{
  "source": "PROFESSIONAL",
  "scheduledDate": "2026-08-11T00:00:00.000Z",
  "frequency": "1m"
}

Subscription

A Subscription action indicates the user's subscription for a paid smallcase needs attention — most commonly that they've been unsubscribed (e.g. a failed mandate or auto-downgrade). Use it to prompt re-subscription or payment.

{
  "scid": "GATEMO_0004",
  "status": "UNSUBSCRIBED",
  "unsubscribeDate": "2026-07-06T00:00:00.000Z",
  "reason": "Payment processing failed",
  "userPlanId": "69ca8fe0e8c390563c0ba5a1"
}

Authentication

Every payload includes a checksum field that you must verify on your server before processing it, to confirm the request genuinely came from smallcase Gateway.

Checksum formula:

HMAC-SHA256( timestamp + smallcaseAuthId, API_SECRET )

Where timestamp is the top-level timestamp and smallcaseAuthId is data.smallcaseAuthId, concatenated (in that order) and signed with your API_SECRET.

Verification example (Node.js):

const crypto = require('crypto');

function verifyPendingActionsWebhook(payload, apiSecret) {
  const { timestamp, data, checksum } = payload;
  const expected = crypto
    .createHmac('sha256', apiSecret)
    .update(timestamp)
    .update(data.smallcaseAuthId)
    .digest('hex');
  return expected === checksum;
}

Handling recommendations

• Replace, don't append. Each delivery is the full current set of pending actions for the user. Overwrite your stored state for that smallcaseAuthId rather than merging — an action's absence means it's been resolved.
• Verify the checksum before acting on any payload.
• Key by smallcaseAuthId + iscid. Use smallcaseAuthId to find your user and iscid/scid to map to the specific holding/product.
• Expect combinations. A single invested smallcase can carry more than one action type at once (e.g. a fixAction and a rebalanceAction).
• Acknowledge fast. Return 2xx within the 10-second timeout; do heavy processing asynchronously.

FAQ

How often is it sent?

On a recurring schedule (batch). Each run pushes the current snapshot for every eligible user; there is one payload per user per run.

Will I get a webhook when there's nothing pending?

No. A user with no pending actions is not included in a run.

How do I know an action was completed?

It simply stops appearing in subsequent payloads. Because each payload is a full snapshot, reconcile by replacing your stored state.

What identifies the user and the product?

data.smallcaseAuthId identifies the Gateway user; within each investment, iscid identifies the user's specific holding and scid identifies the smallcase product.