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:
- Name: unique within the session.
- Secret: generated automatically if left blank. A secret is displayed once when a hook is created or rotated.
- Signature header and prefix (advanced): defaults to
x-albedo-signatureandsha256=.
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.
x-albedo-event-idis optional (1–128 bytes, no newlines). Repeating an event ID with the same body is deduplicated; reusing the same event ID for a different body returns409(event_conflict).- Deliveries arrive after any currently running turn ends and include a preview of up to 4,000 characters. The agent can read the full stored payload when they need more.
- Received payloads are marked as external data, not as something you said.
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