Docs

Webhooks

Hear about approvals as they are decided, instead of polling.

curl https://www.halto.tech/v1/hooks \
  -H "Authorization: Bearer $HALTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "target_url": "https://hook.example.com/halto" }'
# → { "id": "…", "secret": "…",
#     "target_url": "https://hook.example.com/halto" }

Halto then POSTs each decision to that URL, signed with the secret:

POST /halto HTTP/1.1
Host: hook.example.com
X-Halto-Signature: sha256=<HMAC of the body with the secret>

{ "event": "approval.decided", "approval_id": "…",
  "status": "approved", "decided_at": "…" }

Check the signature

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

const secret = process.env.HALTO_HOOK_SECRET!;
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const signature = String(req.headers["x-halto-signature"] ?? "");
const ok = signature.length === expected.length
  && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  • Sign the raw body as it arrived, before parsing it.
  • The body also carries a unique delivery_id and the send time sent_at: refuse one you've seen, or an old one.
  • GET /v1/hooks lists an agent's subscriptions, and DELETE /v1/hooks/{id} removes one.