Guides

Webhooks

Get low-balance and policy-violation alerts delivered to your own server.

Register an https endpoint on the Developers page. You sign the registration with your owner wallet, so only you can add webhooks for your accounts. You receive a signing secret once; store it, it is not shown again.

Events

Event	When it is sent
`low_balance`	An account's net balance fell below your threshold. At most once per account per UTC day.
`policy_violation`	The SDK refused a payment for a policy reason and reported it, signed by the agent's key.

Verify the signature

Each delivery is a JSON POST with an Unslept-Event header and an Unslept-Signature header of the form t=<unix>,v1=<hex>. The hex is HMAC-SHA256 of t + "." + body with your signing secret. Reject deliveries older than five minutes.

verify.ts

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

export function verify(secret: string, header: string, body: string) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  return want.length === v1.length && timingSafeEqual(Buffer.from(want), Buffer.from(v1));
}

Example payload

low_balance.json

{
  "type": "low_balance",
  "account": "0x...",
  "owner": "0x...",
  "netBalance": "3200000",
  "threshold": "5000000",
  "message": "Account 0x... holds 3.2 USDG net, below your 5 USDG threshold.",
  "at": "2026-10-31T09:00:00.000Z"
}