Webhooks

Set a webhook URL in the project's settings. Huddle POSTs each event to it, signed with the project's secret (whsec_…, shown next to the URL).

import { HuddleServer } from "@huddle/sdk/server";

app.post("/webhooks/huddle", async (req, res) => {
  const event = HuddleServer.verifyWebhook(process.env.HUDDLE_WEBHOOK_SECRET!, req.rawBody, req.headers["x-huddle-signature"]);
  if (!event) return res.status(401).end();
  if (event.type === "wallet_linked") markLinked(event.userId, event.address);
  if (event.type === "tx" && event.status === "confirmed") celebrate(event.userId, event.signature);
  res.status(200).end();
});

Verify the raw body: re-serialized JSON won't match the signature.

Events

{ "v": 1, "at": 1795276420479, "type": "wallet_linked", "userId": "80351110224678912", "address": "9xQe…" }
{ "v": 1, "at": …, "type": "wallet_unlinked", "userId": "…", "address": "…" }
{ "v": 1, "at": …, "type": "tx", "key": "round:42", "kind": "transfer-sol",
  "status": "held" | "confirmed" | "failed", "signature": "…", "userId": "…", "error": null }
{ "v": 1, "at": …, "type": "watch", "name": "treasury", "address": "…", "signature": "…", "slot": 312345678, "failed": false }
{ "v": 1, "at": …, "type": "ping" }

Signature

x-huddle-signature: t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256 of "<t>.<raw body>" with your secret. Refuse anything older than five minutes. The dashboard's Send test event sends a ping; Rotate secret replaces the secret at once.

Deliveries are retried four times on network errors, 429 and 5xx. Treat events as hints, and read the API (huddle.tx(key), huddle.wallet(userId)) when you need the authoritative state.

NextClient SDK