← Docs

Webhooks

Coming Soon

Real-Time Webhooks

Get notified when treasury events happen. Webhooks push real-time updates to your server so your agents and systems can react immediately.

Event Types

deposit.completed

A deposit has been processed and funds converted to BTC/ETH.

Treasury
borrow.completed

A borrow request has been approved and funds disbursed.

Treasury
convert.completed

A USDC conversion to BTC or ETH has completed.

Treasury
repay.completed

A manual or auto repayment has been processed.

Treasury
health.warning

Health score dropped below 70 or LTV exceeded 45%.

Health
health.critical

Health score dropped below 50 or LTV exceeded 55%.

Health
auto_repay.triggered

Auto-repay activated to protect against liquidation.

Health

Payload Format

Example: deposit.completed

JSON
{
  "id": "evt_abc123def456",
  "type": "deposit.completed",
  "created_at": "2026-02-28T12:00:00Z",
  "data": {
    "deposit_id": "dep_abc123",
    "amount_usdc": 10000,
    "fee_usdc": 200,
    "net_amount": 9800,
    "allocation": { "btc": 60, "eth": 40 },
    "status": "completed"
  }
}

Headers included with every webhook

X-Stackit-SignatureHMAC-SHA256 signature for payload verification.
X-Stackit-EventThe event type (e.g., deposit.completed).
X-Stackit-DeliveryUnique delivery ID for deduplication.
Content-TypeAlways application/json.

Retry Policy

Max Retries

3

Backoff

Exponential

Timeout

30s

Webhooks are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes. Your endpoint must respond with a 2xx status within 30 seconds. After 3 failed attempts, the webhook is marked as failed and logged for manual review.

Signature Verification

Every webhook includes an X-Stackit-Signature header containing an HMAC-SHA256 signature of the raw request body. Always verify this signature before processing the webhook.

Verify & Handle Webhooks

TypeScript
import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhooks/stackit', (req, res) => {
  const signature = req.headers['x-stackit-signature'] as string;
  const isValid = verifyWebhook(
    JSON.stringify(req.body),
    signature,
    process.env.STACKIT_WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  switch (event.type) {
    case 'deposit.completed':
      console.log(`Deposit ${event.data.deposit_id} completed`);
      break;
    case 'health.warning':
      console.log(`Health warning: score ${event.data.health_score}`);
      break;
    case 'auto_repay.triggered':
      console.log(`Auto-repay: LTV ${event.data.ltv_before} → ${event.data.ltv_after}`);
      break;
  }

  res.status(200).send('OK');
});

Ready to integrate?

Book a Treasury Design Call to get webhook access and start building.