albedo docs

Webhooks

Accept signed HTTP webhooks from external services and deliver their payloads to the agent in a specific persistent session.

On this page: Create a webhook, Send signed deliveries, Tell the agent what they are for, and Rotate secrets and agent management.

The webhooks extension is off by default. Open /extensions in the terminal or web client and enable webhooks before creating a hook.

Create a webhook

Open /webhooks in the terminal or web client and create a hook for a session:

Each hook displays its delivery URL once created. The webhook intake listener binds on loopback when the daemon starts, so read the current URL from /webhooks rather than hardcoding a port that changes across daemon restarts.

Send signed deliveries

External callers POST to the hook's delivery URL with a body of at most 64 KiB and an HMAC-SHA256 hex signature of the raw request body:

sig=$(openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex body.json | awk '{print $NF}')
curl -X POST "$WEBHOOK_URL" \
  -H "x-albedo-signature: sha256=$sig" \
  -H "x-albedo-event-id: evt-123" \
  --data-binary @body.json

Accepted requests return 202 with {"delivery_id": "..."} and enqueue the delivery in the agent's inbox.

Tell the agent what they are for

A delivery is only data until the agent knows why it arrives. Explain it once, in the session the hook belongs to:

i hooked ci up to you. when a run on main fails, could you look at what broke and tell me what you think happened? the green ones you can let go by.

the deploy hook is yours too. can you keep a little log of versions and times in deploys.md, so we both know what went out when?

Rotate secrets and agent management

Use /webhooks to enable or disable a hook, inspect recent deliveries, or rotate a signing secret.

By default, only a human can create, edit, rotate, enable, disable, or delete hooks. To let an agent manage their own hooks, so that you can say "make a webhook for the CI and give me its secret", turn on agent management for that session on the /webhooks page. An agent can always list their hooks and read the deliveries.

See the Webhooks implementation reference for storage and transfer details.

Previous discord Next skills & instructions