Outbound callback support for queued / asynchronous agent replies.
The standard agent webhook contract has three reply modes:
response— the agent computed an answer synchronously and returns it in the HTTP response.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...callback— same asqueued, but the agent commits to POSTing the final answer to acallback_urlprovided 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)— POSTpayload(JSON-encoded) to an HTTPSopts.url, attaching an HMAC signature header when a signing secret is configured. Returns{ok, status, error?, attempt-ms}.from-body(body)— extract aCallbackOptionsfrom the webhook body'scallback_urlfield, returningnullwhen 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:
- Pull a
CallbackOptionsfrom the inbound body viafrom-body. - Reply synchronously with
mode: "queued"andcallback: true. - 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-urlcallback_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 tox-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 (or0when the call never reached the server).error— human-readable error string on failure.attempt-ms— wall-clock time spent on the attempt.