Outbound callback support for queued / asynchronous agent replies.

The standard agent webhook contract has three reply modes:

  1. response — the agent computed an answer synchronously and returns it in the HTTP response.
  2. queued — the agent kicked off async work (memory recall, LLM call) and returns a placeholder. The transport client is expected to listen on the Hot run stream for the eventual answer, or...
  3. callback — same as queued, but the agent commits to POSTing the final answer to a callback_url provided by the caller. This is the right shape for Slack / Telegram / Discord integrations that don't speak Hot's run stream natively.

This module is the agent-side helper for mode 3.

Surface

  • CallbackOptions — {url, signing-secret-env?, signing-header?, timeout-ms?, headers?}.
  • post-callback(payload, opts) — POST payload (JSON-encoded) to an HTTPS opts.url, attaching an HMAC signature header when a signing secret is configured. Returns {ok, status, error?, attempt-ms}.
  • from-body(body) — extract a CallbackOptions from the webhook body's callback_url field, returning null when no callback was requested. from-body(body, signing-secret-env) also signs with the named env var. That name comes from your code, never from the body.

Transports that want callback parity should:

  1. Pull a CallbackOptions from the inbound body via from-body.
  2. Reply synchronously with mode: "queued" and callback: true.
  3. Once the async work finishes, call post-callback(answer, opts).

Values

INTERNAL_TLDS

INTERNAL_TLDS: Vec [
  "localhost",
  "local",
  "internal",
  "intranet",
  "lan",
  "home",
  "corp",
  "svc",
  "arpa"
]

IPV4_ADDRESS

IPV4_ADDRESS: Str "^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])[.]){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])$"

NON_PUBLIC_IPV4

NON_PUBLIC_IPV4: Vec [
  "^(0|10|127)[.]",
  "^100[.](6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])[.]",
  "^169[.]254[.]",
  "^172[.](1[6-9]|2[0-9]|3[01])[.]",
  "^192[.]0[.][02][.]",
  "^192[.]88[.]99[.]",
  "^192[.]168[.]",
  "^198[.](1[89]|51[.]100)[.]",
  "^203[.]0[.]113[.]",
  "^(22[4-9]|2[3-5][0-9])[.]"
]

Functions

from-body

fn (body: Map?): Any
fn (body: Map?, signing-secret-env: Str?): Any

Build a CallbackOptions from a webhook body. Returns null when the caller didn't supply a callback URL. Recognized keys (both kebab-case and snake_case):

  • callback_url / callback-url
  • callback_signing_header / callback-signing-header

To sign the callback, pass the env var name as signing-secret-env. The body cannot choose it: a caller who could name any env var would get that value used as an HMAC key on a POST to their own URL. A callback_secret_env key in the body is ignored.

Convenience for transports that accept callback_url in the inbound payload directly. Non-HTTPS URLs are ignored; callers that need local development callbacks should use streams or construct their own stricter transport-local policy.

Example

::callbacks ::ai::agent::callbacks

opts ::callbacks/from-body({callback_url: "https://example.com/done"}, "CALLBACK_SECRET")
opts.url  // "https://example.com/done"
opts.signing-secret-env  // "CALLBACK_SECRET"
::callbacks/from-body({callback_url: "http://example.com/done"})  // null

is-url-allowed

fn (url: Str?): Bool

Return true when a callback URL is safe for the shared helper to call. The default policy is intentionally narrow, so untrusted webhook bodies cannot direct the worker at internal services. Callbacks must be HTTPS, carry no user@ part or backslash, and name a public host: a dotted DNS name outside internal suffixes like .internal, or a publicly routable IPv4 address. IPv6 literals and numeric spellings of IPv4 (2130706433, 0x7f.0.0.1, 127.1) are refused.

This checks the URL only. A public name that resolves to a private address still passes, so network egress rules remain the real boundary for workers that can reach internal services.

Example

::callbacks ::ai::agent::callbacks

::callbacks/is-url-allowed("https://example.com/hook")  // true
::callbacks/is-url-allowed("http://example.com/hook")  // false
::callbacks/is-url-allowed("https://10.0.0.5/hook")  // false
::callbacks/is-url-allowed("https://x@127.0.0.1/hook")  // false

post-callback

fn (payload: Any, opts: CallbackOptions?): CallbackResult

POST payload to opts.url as JSON, optionally signing the body with HMAC-SHA256. Returns a CallbackResult capturing status and elapsed time so the agent can log / retry.

payload may be any value — it's wrapped through ::hot::json/to-json before transmission.

Example

::callbacks ::ai::agent::callbacks

opts ::callbacks/CallbackOptions({
    url: "https://example.com/agent/callback",
    signing-secret-env: "AGENT_CALLBACK_SECRET",
})
result ::callbacks/post-callback({text: "Done."}, opts)
if(result.ok, `delivered in ${result.attempt-ms}ms`, result.error)

Types

CallbackOptions

CallbackOptions type {
    url: Str,
    signing-secret-env: Str?,
    signing-secret: Str?,
    signing-header: Str?,
    headers: Map?,
    timeout-ms: Int?
}

Configuration for a callback POST.

  • url — destination URL.
  • signing-secret-env — env var holding the HMAC secret used to sign the JSON body.
  • signing-secret — literal secret (rare; prefer env).
  • signing-header — header name for the signature. Defaults to x-hot-signature. The value is "sha256=<hex>".
  • headers — extra headers to send.
  • timeout-ms — reserved (HTTP timeout — currently advisory).

CallbackResult

CallbackResult type {
    ok: Bool,
    status: Int,
    error: Str?,
    attempt-ms: Int
}

Outcome of a callback POST.

  • ok — true when the upstream returned a 2xx status.
  • status — HTTP status code (or 0 when the call never reached the server).
  • error — human-readable error string on failure.
  • attempt-ms — wall-clock time spent on the attempt.