Module callback_contract 

HTTP callback ingress contract — wire types, signing, header names.

Shared between:

• awa-worker’s HttpWorker which signs the outgoing callback id when posting to a function endpoint.
• awa-ui’s built-in callback handler, which verifies incoming requests.
• User-owned callback receivers (FastAPI/axum/etc.) that want to share the exact same authentication and payload contract — see ADR-027.

See ADR-018 (HTTP worker) and ADR-027 (callback ingress as a deployable surface).

The signature scheme is BLAKE3 keyed-hash over the UTF-8 bytes of the callback id, rendered as lowercase hex. Verification uses the constant-time PartialEq implementation on blake3::Hash.

use awa_model::callback_contract::{sign, verify, SIGNATURE_HEADER};

let secret = [7u8; 32];
let id = "550e8400-e29b-41d4-a716-446655440000";
let signature = sign(&secret, id);
assert!(verify(&secret, id, &signature));
assert_eq!(SIGNATURE_HEADER, "X-Awa-Signature");

Structs

CallbackResponse

Response body returned by the built-in callback handler. User-owned receivers SHOULD mirror this shape so generic clients work against any receiver implementation.

CompletePayload

Body of POST /api/callbacks/{id}/complete.

FailPayload

Body of POST /api/callbacks/{id}/fail.

HeartbeatPayload

Body of POST /api/callbacks/{id}/heartbeat. timeout_seconds defaults to DEFAULT_HEARTBEAT_TIMEOUT_SECS when omitted.

Constants

DEFAULT_CALLBACK_PATH_PREFIX

Path prefix used by awa serve and the built-in callback handler. The full URL of a callback action is {callback_base_url}{prefix}/{callback_id}/{action}.

DEFAULT_HEARTBEAT_TIMEOUT_SECS

Default heartbeat timeout in seconds (1 hour). Used when an inbound heartbeat request omits timeout_seconds.

SIGNATURE_HEADER

HTTP header carrying the hex-encoded BLAKE3 keyed-hash signature of the callback id.

Functions

callback_url

Build the URL for a given callback action.

sign

Sign a callback id with the shared secret. Returns lowercase hex.

verify

Verify a provided signature against the expected one. Returns true only when the signature is well-formed hex and equals the keyed hash of the callback id. Comparison is constant-time.