Skip to content

Document and support user-owned callback API layers #281

@hardbyte

Description

@hardbyte

Context

Some users will not want Awa to own the HTTP server that receives callbacks. They may already have FastAPI, Starlette, Django, Flask, axum, or another API layer and want to expose Awa callback routes inside that application.

Today the docs say users can mount equivalent handlers around admin functions, but that leaves them to copy the signing algorithm, payload contract, timeout validation, and error behavior.

Related design draft: #277. Shared callback contract/auth is tracked in #278.

Proposed work

Provide an officially supported integration path for user-owned callback API layers.

Rust direction:

  • expose lower-level callback receiver service functions that are not tied to axum routing;
  • document how to call them from an existing axum application;
  • make the axum callback-only router from Add a callback-only receiver router and CLI #279 a thin wrapper around those functions.

Python direction:

  • expose or document a small helper for verifying X-Awa-Signature;
  • provide FastAPI-style examples for complete/fail/heartbeat routes;
  • show how to resolve callbacks via the Python admin/client API;
  • keep the examples aligned with the shared contract from Extract shared callback contract and signature helpers #278.

Acceptance criteria

  • Docs include a minimal custom axum example.
  • Docs include a minimal FastAPI example.
  • Examples do not reimplement the signature algorithm inline when a helper exists.
  • The examples cover complete, fail, and heartbeat.
  • The security docs clearly state that callback routes are mutating endpoints and must be signed or otherwise protected.
  • If Python helpers are added, they have parity tests against the Rust signing implementation.

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation improvementsfeatureNew functionality

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions