Webhooks

{
  "id": "01HF3K6...",
  "type": "payout.crypto.withdraw.approval",
  "createdAt": "2026-05-18T12:34:56.000Z",
  "data": {
    "withdrawal": {
      "id": "8a3f...",
      "userId": "...",
      "externalId": "merchant-ref-001",
      "forUserId": "uuid-or-null",
      "forUserExternalId": "your-subuser-ref-or-null",
      "status": "pending_callback",
      "chain": "ethereum",
      "token": "USDC",
      "tokenAddress": "0xa0b8...",
      "destination": "0x...",
      "amountCents": 100000,
      "feeCents": 247,
      "amountWei": "100000000",
      "txHash": null,
      "failureReason": null,
      "callbackAttempts": 0,
      "createdAt": "2026-05-18T12:34:56.000Z",
      "broadcastAt": null,
      "confirmedAt": null
    }
  }
}

interface WebhookEnvelope {
  id: string;                 // delivery UUID — same value as `webhook-id` header
  type: string;               // event type, e.g. "trade.completed"
  createdAt: string;          // ISO-8601
  data:
    | {
        trade: Trade;                   // same shape as GET /merchant/trades/{id}
        settlement?: { houseFeeCents: number; merchantFeeCents: number };
        refund?: {                      // trade.refunded — per refunded item, USD
          itemId: string;               // matches TradeItem.id
          externalId?: string;          // your own per-item ref, when you supplied one
          buyerFault: boolean;
          refunded: number;             // returned to the wallet (sourcing + fee)
          penalty: number;              // withheld on buyer fault, else 0
        };
      }
    | { deposit: Deposit }
    | {
        deposit: Deposit;
        forUserExternalId: string | null;
      }                                  // payout.crypto.deposit.completed
    | {
        withdrawal: PayoutWithdrawal;    // shape mirrors GET /payout/crypto/withdrawals/{id}
      };                                 // payout.crypto.withdraw.{approval,broadcast,confirmed,refunded}
}

import express from "express";
import { verifyWebhook, isError } from "@skinshark/sdk";

const app = express();
const SECRET = process.env.SKINSHARK_WEBHOOK_SECRET!;

app.post(
  "/webhooks/skinshark",
  express.raw({ type: "application/json" }),     // raw bytes, not parsed JSON
  async (req, res) => {
    let event;
    try {
      event = verifyWebhook(req.body, req.headers, { secret: SECRET });
    } catch (e) {
      if (isError(e, "INVALID_SIGNATURE")) return res.status(401).end();
      throw e;
    }

    // event is typed as a discriminated WebhookEvent union.
    if (await alreadyProcessed(event.id)) return res.status(200).end();
    await handleEvent(event);
    await markProcessed(event.id);
    return res.status(200).end();
  },
);

import { createHmac, timingSafeEqual } from "node:crypto";
import { Buffer } from "node:buffer";

interface VerifyResult {
  ok: boolean;
  reason?: "missing-header" | "stale-timestamp" | "bad-signature";
}

export function verifySkinSharkSignature(
  id: string | undefined,
  timestamp: string | undefined,
  signatureHeader: string | undefined,
  rawBody: Buffer,
  secret: string,
  toleranceSec = 300,
): VerifyResult {
  if (!id || !timestamp || !signatureHeader) return { ok: false, reason: "missing-header" };

  const skew = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(skew) || skew > toleranceSec) return { ok: false, reason: "stale-timestamp" };

  // Header format: t=<ts>,s=<sig>[,s1=<sig>]
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => {
      const i = kv.indexOf("=");
      return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
    }),
  );

  const candidates = [parts.s, parts.s1].filter(Boolean) as string[];
  if (candidates.length === 0) return { ok: false, reason: "bad-signature" };

  const signed = `${id}.${timestamp}.${rawBody.toString("utf8")}`;
  const expected = createHmac("sha256", secret).update(signed).digest("base64url");
  const a = Buffer.from(expected);

  for (const c of candidates) {
    const b = Buffer.from(c);
    if (a.length === b.length && timingSafeEqual(a, b)) return { ok: true };
  }
  return { ok: false, reason: "bad-signature" };
}

ngrok http 3000
# Set dashboard webhook URL to: https://<id>.ngrok-free.app/webhooks/skinshark