# Webhooks The `webhooks` extension accepts signed deliveries for a persistent session. Its [extension registration](../src/albedo/harness/extensions/webhooks/extension.gleam) connects the service, storage, transfer adapter, and Python binding. See also [Discord](discord.md), which delivers another kind of external event. ## Setup [`sdk/webhook_address`](../src/albedo/harness/sdk/webhook_address.gleam) constructs the intake path and, given a port, a loopback delivery URL. The [daemon server](../src/albedo/daemon/server.gleam) records the port in [`daemon/webhook_intake`](../src/albedo/daemon/webhook_intake.gleam) 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`](../src/albedo/transfer.gleam), 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`](../src/albedo/harness/extensions/webhooks/ledger.gleam) defaults the header to `x-albedo-signature` and the prefix to `sha256=`. The [terminal client](tui.md) and [web client](web.md) provide management pages. ## Delivery [`accept`](../src/albedo/harness/extensions/webhooks/ledger.gleam) checks the signature and rejects bodies over 64 KiB. The ledger stores an accepted delivery and posts it to the session's [inbox](inbox.md) 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](../src/albedo/harness/extensions/webhooks/service.gleam) 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`](../src/albedo/harness/sdk/mail.gleam). 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](extensions.md#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](workspaces.md#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`](../src/albedo/daemon/moves.gleam) 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`](../priv/python/albedo_plugins/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](../src/albedo/harness/extensions/webhooks/rpc.gleam) enforces the session and permission checks. ## Related pages - [All topics](README.md) - [Change guidance](contributing.md) - [Discord](discord.md) - [Inbox](inbox.md) - [Durable operation admission](operations.md)