Webhooks

Register webhooks and receive real-time Portfolio Wallet events.

Subscribe to webhooks to receive real-time notifications about wallet workflow, deposit, rebalance, withdrawal, payout, and strategy lifecycle changes.

​

Register a webhook

curl -X POST "$BASE_URL/v2/webhooks" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/ground/webhook",
	    "events": [
	      "portfolio_wallet.status_changed",
	      "portfolio_wallet.deposit.status_changed",
	      "portfolio_wallet.withdrawal.status_changed",
	      "portfolio_wallet.withdrawal.payout.status_changed",
	      "portfolio_wallet.approval.status_changed",
	      "portfolio_wallet.strategy.status_changed",
	      "portfolio_wallet.rebalance.status_changed",
	      "portfolio_wallet.risk.alert.triggered",
	      "portfolio_wallet.risk.alert.resolved",
	      "portfolio_wallet.risk.action.status_changed",
	      "portfolio_wallet.risk.unwind.completed"
	    ],
    "description": "Production webhook endpoint"
  }'

The create response includes id, url, events, createdAt, and secret. Store secret on the server only (env var / secret manager). The secret field is only returned on create — it is not included when listing endpoints.

{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
	  "url": "https://example.com/ground/webhook",
	  "events": [
	    "portfolio_wallet.deposit.status_changed",
	    "portfolio_wallet.rebalance.status_changed"
	  ],
  "createdAt": "2026-02-05T08:00:00.000Z",
  "secret": "abcdef1234567890..."
}

Only portfolio_wallet.* event types are accepted. Requests that include event types outside the portfolio_wallet.* namespace will be rejected with a validation error.

​

List webhooks

curl -X GET "$BASE_URL/v2/webhooks?limit=25" \
  -H "Authorization: Bearer $API_TOKEN"

The list is returned under data. Pass a non-null nextCursor as cursor to fetch the next page. Note that secret is not included in list responses. See API Conventions for the list envelope.

{
  "data": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "url": "https://example.com/ground/webhook",
      "events": [
        "portfolio_wallet.deposit.status_changed",
        "portfolio_wallet.rebalance.status_changed"
      ],
      "createdAt": "2026-02-05T08:00:00.000Z"
    }
  ],
  "nextCursor": null
}

​

Delete a webhook

curl -X DELETE "$BASE_URL/v2/webhooks/$ENDPOINT_ID" \
  -H "Authorization: Bearer $API_TOKEN"

Returns { "id": "...", "deleted": true } on success.

​

Portfolio Wallet events

Event	Fires when
portfolio_wallet.status_changed	The wallet’s lifecycle status changes (e.g. creating -> idle, rebalance_active, withdrawal_active, or failed)
portfolio_wallet.deposit.status_changed	A deposit posts to the wallet after observed finality and ledger accounting
portfolio_wallet.withdrawal.status_changed	A withdrawal workflow changes status or step progress
portfolio_wallet.withdrawal.payout.status_changed	An individual withdrawal payout leg changes status or step progress
portfolio_wallet.approval.status_changed	An organization approval becomes pending, approved, rejected, or expired
portfolio_wallet.strategy.status_changed	A strategy update is applied
portfolio_wallet.rebalance.status_changed	A rebalance workflow transitions status
portfolio_wallet.risk.alert.triggered	A portal-configured risk rule triggers an alert
portfolio_wallet.risk.alert.resolved	A risk alert is resolved
portfolio_wallet.risk.action.status_changed	A risk action changes status
portfolio_wallet.risk.unwind.completed	A risk-triggered unwind finishes moving value to cash

​

Handle an event

1. Verify the signature against the raw request body before parsing it.
2. Use Ground-Event-Id to recognize duplicate deliveries.
3. Queue processing and respond with 200 promptly.
4. Read the latest wallet or operation state before updating your application. Use polling to recover missed updates.

​

Event payloads

​

portfolio_wallet.status_changed

{
  "event": "portfolio_wallet.status_changed",
  "organizationId": "43c78f4f-44a7-45ff-a524-8f010f7a4c72",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "previousStatus": "idle",
  "status": "rebalance_active",
  "occurredAt": "2026-02-05T10:28:00.000Z"
}

​

portfolio_wallet.deposit.status_changed

{
  "event": "portfolio_wallet.deposit.status_changed",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "observedAt": "2026-02-05T09:45:00.000Z",
  "deposit": {
    "id": "2a3ad0af-11b3-41d5-96c5-2b9d8799f1e2",
    "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
    "amount": "50000.000000",
    "token": "usdc",
    "chain": "ethereum",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "txHash": "0xabc123...",
    "status": "completed",
    "cashPositionId": "cash:ethereum:usdc",
    "createdAt": "2026-02-05T09:40:00.000Z",
    "completedAt": "2026-02-05T09:45:00.000Z"
  }
}

​

portfolio_wallet.withdrawal.status_changed

{
  "event": "portfolio_wallet.withdrawal.status_changed",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "observedAt": "2026-02-05T11:05:00.000Z",
  "withdrawal": {
    "id": "11b17950-1f5c-4d36-8f0d-0f3d1d0c6a45",
    "amountRequestedUsd": "65000.000000",
    "amountPaidUsd": null,
    "amountPaidToPartnerUsd": null,
    "feeUsd": "0.000000",
    "destinationChain": "ethereum",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "destinationToken": "usdc",
    "status": "processing",
    "legsCompleted": 0,
    "legsTotal": 1,
    "payoutLegs": [
      {
        "status": "pending_customer_approval",
        "amountUsd": "65000.000000",
        "from": { "kind": "cash", "id": "cash:ethereum:usdc", "label": "Cash (Ethereum)" },
        "to": { "kind": "external_payout", "id": "external_payout:ethereum:usdc", "label": "External payout (Ethereum)" },
        "startedAt": "2026-02-05T11:00:00.000Z",
        "completedAt": null,
        "stepsCompleted": 0,
        "stepsTotal": 1,
        "steps": [
          {
            "name": "Sending payout",
            "chain": "ethereum",
            "state": "pending_customer_approval",
            "txKind": "external_payout_transfer",
            "stepKind": "external_payout_transfer",
            "startedAt": "2026-02-05T11:00:00.000Z",
            "completedAt": null,
            "cancelledAt": null,
            "stepOrdinal": 0,
            "protocolType": "external_payout",
            "sequenceRole": "external_payout_transfer"
          }
        ]
      }
    ],
    "failureReason": null,
    "createdAt": "2026-02-05T11:00:00.000Z",
    "completedAt": null
  }
}

The withdrawal object has the same fields as the response from GET /v2/wallets/:id/withdrawals/:withdrawalId, including feeUsd and the optional Stellar memo when provided. It also includes payout legs and their current execution steps. See Withdraw Funds for the full payoutLegs structure.

​

portfolio_wallet.approval.status_changed

{
  "event": "portfolio_wallet.approval.status_changed",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "observedAt": "2026-10-09T17:45:00.000Z",
  "approval": {
    "activityId": "01a11d9f-e6a3-7577-82a9-323801484c76",
    "activityKind": "stellar_trustline",
    "chain": "stellar_testnet",
    "status": "pending",
    "requestedAt": "2026-10-09T17:45:00.000Z",
    "validBefore": "2026-10-09T18:00:00.000Z",
    "resolvedAt": null
  }
}

Approval statuses are pending, approved, rejected, and expired. Use activityId with the transaction approval endpoints. Stellar deposit setup uses stellar_trustline. Withdrawal payouts use external_payout across supported networks, including Stellar.

​

portfolio_wallet.withdrawal.payout.status_changed

{
  "event": "portfolio_wallet.withdrawal.payout.status_changed",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "observedAt": "2026-02-05T12:40:00.000Z",
  "payout": {
    "id": "4f70f27a-760c-45f1-8ac9-01878d8d2d6c",
    "status": "completed",
    "turnkeyActivityId": null,
    "approvalRequestedAt": null,
    "approvalValidBefore": null,
    "amountUsd": "35000.000000",
    "feeUsd": "0.000000",
    "txHash": "0xabc123...",
    "failureReason": null,
    "steps": [
      {
        "name": "Redeeming from Syrup USDC",
        "stepKind": "syrup_request_redeem",
        "sequenceRole": "yield_redeem",
        "protocolType": "syrup",
        "stepOrdinal": 0,
        "chain": "ethereum",
        "txKind": "yield_source_redeem",
        "state": "completed",
        "startedAt": "2026-02-05T12:35:00.000Z",
        "completedAt": "2026-02-05T12:36:00.000Z",
        "cancelledAt": null
      },
      {
        "name": "Sending payout",
        "stepKind": "external_payout_transfer",
        "sequenceRole": "external_payout_transfer",
        "protocolType": "external_payout",
        "stepOrdinal": 1,
        "chain": "ethereum",
        "txKind": "external_payout_transfer",
        "state": "completed",
        "startedAt": "2026-02-05T12:38:00.000Z",
        "completedAt": "2026-02-05T12:40:00.000Z",
        "cancelledAt": null
      }
    ],
    "createdAt": "2026-02-05T12:34:00.000Z",
    "completedAt": "2026-02-05T12:40:00.000Z"
  }
}

​

portfolio_wallet.strategy.status_changed

{
  "event": "portfolio_wallet.strategy.status_changed",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "observedAt": "2026-02-05T09:30:00.000Z",
  "strategy": {
    "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
    "requestId": "6d74dc1c-f1b5-4f2c-8f33-9f7b9e27cd4b",
    "status": "completed",
    "allocations": [
      { "yieldSourceId": "syrup-usdc", "pct": 40 },
      { "yieldSourceId": "morpho-gauntlet-usdc", "pct": 30 },
      { "yieldSourceId": "morpho-steakhouse-usdc", "pct": 30 }
    ],
    "createdAt": "2026-02-05T09:29:00.000Z"
  }
}

​

portfolio_wallet.rebalance.status_changed

{
  "event": "portfolio_wallet.rebalance.status_changed",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "observedAt": "2026-02-05T10:30:00.000Z",
  "rebalance": {
    "id": "b6c7d8e9-1234-4abc-8def-0123456789ab",
    "status": "processing",
    "reason": "deposit_deployment",
    "amountUsd": "50000.000000",
    "legsCompleted": 0,
    "legsTotal": 2,
    "rebalanceLegs": [
      {
        "status": "processing",
        "amountUsd": "25000.000000",
        "from": { "kind": "cash", "id": "cash:ethereum:usdc", "label": "Cash (Ethereum)" },
        "to": { "kind": "yield_source", "id": "morpho-gauntlet-usdc", "label": "Morpho Gauntlet USDC Prime" },
        "startedAt": "2026-02-05T10:29:00.000Z",
        "completedAt": null,
        "stepsCompleted": 0,
        "stepsTotal": 1,
        "steps": [
          {
            "name": "Depositing into Morpho Gauntlet USDC Prime",
            "chain": "ethereum",
            "state": "processing",
            "txKind": "yield_source_deposit",
            "stepKind": "yield_source_deposit",
            "startedAt": "2026-02-05T10:29:00.000Z",
            "completedAt": null,
            "cancelledAt": null,
            "stepOrdinal": 0,
            "protocolType": "morpho",
            "sequenceRole": "yield_deposit"
          }
        ]
      }
    ],
    "failureReason": null,
    "createdAt": "2026-02-05T10:28:00.000Z",
    "startedAt": "2026-02-05T10:29:00.000Z",
    "completedAt": null
  }
}

Rebalance and withdrawal step objects describe execution progress. Read broadcast transaction hashes from payout rows when available; individual steps do not always include a transaction hash.

​

Error responses

Webhook registration and management endpoints return errors in a consistent {error, code} structure:

{
  "error": "Unsupported event types: portfolio_wallet.legacy_event",
  "code": "validation_error"
}

​

Delivery and headers

Ground POSTs to your registered url with these headers:

Header	Description
Content-Type	application/json
Ground-Event-Id	Unique event identifier
Ground-Event-Type	Event type (e.g. portfolio_wallet.rebalance.status_changed)
Ground-Signature	HMAC signature for verification

​

Signature verification

Ground uses a Stripe-style HMAC scheme:

• Header format: Ground-Signature: t=<unix_timestamp>,v1=<hex_hmac>
• HMAC: v1 = HMAC_SHA256(key = secret, message = t + "." + rawBody)
• rawBody is the exact request body string (before JSON.parse).

​

Node / Express verification example

const crypto = require("crypto");
const express = require("express");

function verifyGroundSignature(
  rawBody,
  signatureHeader,
  signingSecret,
  toleranceSeconds = 300,
) {
  if (!signatureHeader) throw new Error("Missing Ground-Signature header");

  const parts = signatureHeader.split(",");
  const tPart = parts.find((p) => p.startsWith("t="));
  const v1Part = parts.find((p) => p.startsWith("v1="));
  if (!tPart || !v1Part)
    throw new Error("Invalid Ground-Signature header format");

  const timestamp = Number(tPart.split("=")[1]);
  const signature = v1Part.split("=")[1];

  // Optional replay protection
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) {
    throw new Error("Ground-Signature timestamp outside allowed window");
  }

  const payloadToSign = `${timestamp}.${rawBody}`;
  const computed = crypto
    .createHmac("sha256", signingSecret)
    .update(payloadToSign)
    .digest("hex");

  const expected = Buffer.from(computed, "utf8");
  const actual = Buffer.from(signature, "utf8");
  if (
    expected.length !== actual.length ||
    !crypto.timingSafeEqual(expected, actual)
  ) {
    throw new Error("Invalid Ground-Signature");
  }
}

const app = express();

// Use raw body so you can verify before parsing
app.post(
  "/ground/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");
    const signatureHeader = req.get("Ground-Signature");
    const signingSecret = process.env.GROUND_WEBHOOK_SECRET;

    try {
      verifyGroundSignature(rawBody, signatureHeader, signingSecret);
    } catch (err) {
      console.error("Webhook signature verification failed:", err.message);
      return res.status(400).json({ error: "Invalid signature" });
    }

    const event = JSON.parse(rawBody);

    if (event.event === "portfolio_wallet.withdrawal.status_changed") {
      // handle withdrawal status change
    }

    res.status(200).json({ received: true });
  },
);

​

Quick checklist

• Register a webhook and persist secret.
• Verify every request with t + "." + rawBody and constant-time compare.
• Enforce a timestamp window and use HTTPS.
• Log Ground-Event-Id and Ground-Event-Type for debugging.
• Respond with 200 quickly — do heavy processing asynchronously.

​

Stock conversion details

For a completed stock conversion, a rebalance or withdrawal leg can include assetTrades. Each entry identifies the stock, buy or sell side, exact stock and USDC native quantities, chain, and transaction hash. It appears after finalized settlement; an indicative quote is not a completed trade. See webhook payload examples.