Webhooks

{
  "id": "6f1c2a3b-9d0e-4f7a-8c1b-6e5d3f4a2c9b",
  "type": "account.active",
  "apiVersion": "2026-08-19",
  "createdAt": "2026-11-06T10:16:00.000Z",
  "data": { "...": "the payload below" }
}

Content-Type:       application/json
User-Agent:         Kash-Webhooks/1.0
X-Kash-Signature:   t=1792000000000,v1=<hex-hmac-sha256>
X-Kash-Event-Id:    6f1c2a3b-9d0e-4f7a-8c1b-6e5d3f4a2c9b
X-Kash-Event-Type:  account.active
X-Kash-Api-Version: 2026-08-19

{
  "accountId": "7a1c2e3d-4b5f-4a6e-8d7c-1b2a3c4d5e6f",
  "externalId": "hsp-user-8841",
  "status": "active",
  "depositAddress": "8yYpcE7Jx9NmXNMGR6NGumBUu4UBpMTVQW44P9hwikyh",
  "activatedAt": "2026-11-06T10:16:00.000Z"
}

{
  "accountId": "7a1c2e3d-4b5f-4a6e-8d7c-1b2a3c4d5e6f",
  "externalId": "hsp-user-8841",
  "status": "provisioning_failed",
  "reason": "privy_refused",
  "failedAt": "2026-11-06T10:16:00.000Z"
}

{
  "accountId": "7a1c2e3d-4b5f-4a6e-8d7c-1b2a3c4d5e6f",
  "externalId": "hsp-user-8841",
  "previousDestination": { "network": "solana", "address": "8yYpcE7Jx9NmXNMGR6NGumBUu4UBpMTVQW44P9hwikyh" },
  "destination": { "network": "arc", "address": "0x2c7536e3605d9c16a7a3d7b1898e529396a65c23" },
  "changedAt": "2026-11-06T09:30:00.000Z"
}

{
  "accountId": "7a1c2e3d-4b5f-4a6e-8d7c-1b2a3c4d5e6f",
  "externalId": "hsp-user-8841",
  "status": "released",
  "releasedAt": "2026-11-06T12:00:00.000Z"
}

{
  "accountId": "7a1c2e3d-4b5f-4a6e-8d7c-1b2a3c4d5e6f",
  "externalId": "hsp-user-8841",
  "withdrawalId": "0b6e1f7a-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "amountAtomic": "2500000",
  "deliveredAmountAtomic": null,
  "minimumDeliveredAtomic": "2490000",
  "destination": { "network": "arc", "address": "0x2c7536e3605d9c16a7a3d7b1898e529396a65c23" }
}

{
  "accountId": "7a1c2e3d-4b5f-4a6e-8d7c-1b2a3c4d5e6f",
  "externalId": "hsp-user-8841",
  "payoutId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "marketId": "7a6e9c0a-3f4f-4c43-b6ab-1b2f0c8e3c91",
  "outcomeIndex": 1,
  "amountAtomic": "5000000",
  "chainRef": "solana:mainnet-beta",
  "transactionHash": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW",
  "paidAt": "2026-11-06T11:00:00.000Z"
}

import express from 'express';
import { KashClient, KashWebhookSignatureError, isUnknownWebhookEvent } from '@kashdao/sdk';

const app = express();
const kash = new KashClient({ apiKey: process.env.KASH_PARTNER_KEY! });

app.post(
  '/webhooks/kash',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    let event;
    try {
      event = await kash.webhooks.constructEvent(
        req.body.toString('utf8'),
        req.header('x-kash-signature') ?? '',
        process.env.KASH_WEBHOOK_SECRET!,
      );
    } catch (err) {
      if (err instanceof KashWebhookSignatureError) return res.status(400).send('bad signature');
      throw err;
    }

    // At-least-once delivery: process each event id once.
    if (await alreadyProcessed(event.id)) return res.sendStatus(200);

    // A type newer than this SDK version: acknowledge it and log the type.
    if (isUnknownWebhookEvent(event)) return res.sendStatus(200);

    switch (event.type) {
      case 'account.active':
        await markAccountReady(event.data.externalId, event.data.depositAddress);
        break;
      case 'account.destination_changed':
        await checkDestinationChangeWasOurs(event.data.accountId, event.data.changedAt);
        break;
      case 'withdrawal.completed':
      case 'withdrawal.failed':
      case 'payout.completed':
        // Treat the event as a prompt: read the current state from the API.
        await refreshAccount(event.data.accountId);
        break;
      default:
        break;
    }

    await markProcessed(event.id);
    res.sendStatus(200);
  },
);

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyKashSignature(
  rawBody: string,
  header: string,
  secret: string,
  toleranceMs = 5 * 60 * 1000,
): boolean {
  const entries = header.split(',').map((part) => {
    const i = part.indexOf('=');
    return [part.slice(0, i), part.slice(i + 1)] as const;
  });
  const t = Number(entries.find(([k]) => k === 't')?.[1]);
  if (!Number.isFinite(t) || Math.abs(Date.now() - t) > toleranceMs) return false;

  const expected = Buffer.from(
    createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'),
    'hex',
  );
  return entries.some(([k, v]) => {
    if (k !== 'v1') return false;
    const given = Buffer.from(v, 'hex');
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}