Webhooks #
The webhooks extension accepts signed deliveries for a persistent session. Its
extension registration
connects the service, storage, transfer adapter, and Python binding. See also
Discord, which delivers another kind of external event.
Setup #
sdk/webhook_address
constructs the intake path and, given a port, a loopback delivery URL. The
daemon server records the port in
daemon/webhook_intake once the
intake listener binds, and clears it when the intake stops for good. The host
passes webhook_intake.port to the extension as intake_port, a function that
reads the current port. The service reads it from extension.Daemon. Kernel
routes and the /webhooks command read it from extension.Preparation, so the
extension prepares its session contribution with OwnedManagedPlugin. Its
transfer adapter reads addresses through intake_url in
transfer.BindingsContext, which resolves a
path against the live listener and answers None while there is none. Other
transfer owners ignore that field. Read the port each time an address is shown,
and do not keep the number, because a stopped intake must show no URL. A hook
has a secret, an enabled flag, a signature header, and a prefix.
ledger.gleam
defaults the header to x-albedo-signature and the prefix to sha256=. The
terminal client and web client provide management pages.
Delivery #
accept checks the
signature and rejects bodies over 64 KiB. The ledger stores an accepted delivery
and posts it to the session's inbox in one transaction, from
outside, posted once under the delivery's id, read after the running turn ends.
The input contains a bounded preview. webhooks.delivery(id) reads the stored
payload for the session. The
service returns a
delivery ID for an accepted request and reports invalid signatures as an error.
Delivery can fail, including when the inbox is full.
A delivery's letter holds its state: whether it was delivered, how often the
inbox tried, and why it waits. accept posts it as input.Filed under the
delivery's id, filed under the hook. The ledger reads letters through
sdk/mail. Its service, upgrade, and
import run with handles bound to no session and reach the letters of every
hook's session, so webhooks declares Correspondence
(extension capabilities). A delivery is
pending until its letter is delivered. A dropped letter was never delivered, so
its delivery stays pending, as receipts have always shown it. A delivery from
before the inbox, which has no letter, is delivered when its own delivered_at
says so.
A page of pending receipts reads the hook's undelivered letters
(mail.undelivered_in). A page of delivered ones reads its delivered letters
(mail.delivered_in) and its deliveries from before the inbox. Each read uses
an index that holds only rows in that state, so a page reads about the rows it
returns, whatever the hook's or its session's history holds.
ledger.settle gives older deliveries the letter accept gives a new one: a
delivery stored before the inbox existed, still waiting, gets its letter, and a
letter posted before letters were filed is filed under its hook. It reads a page
of deliveries at a time. It runs once when a daemon upgrades, before the service
takes requests, and webhook_upgrades, a table no transfer carries, remembers
that it ran. It runs again for the sessions an import brings, in the transfer
adapter's activate as the import goes live, so a move from an older daemon
shows its receipts at once. Only moves from an older daemon to a newer one are
supported; see moves between versions.
A delivery to a hook whose session moved to another daemon is refused with
status 410. The service tells the session once through
extension.Daemon.tell_refused and answers the sender with
extension.Daemon.hook_gone. Both are bound to
moves by the daemon server.
A received payload is external data, not an instruction. The extension explicitly includes that boundary in its model instructions.
Management #
webhooks.py exposes list,
delivery, create, rotate, configure, enable, disable, and delete.
Management requires a human to enable agent management for the session. Reading
a delivery does not require that permission. Changes to existing hooks take a
revision. The RPC handler
enforces the session and permission checks.