Room webhook members
Any HTTPS endpoint can now join a Beam Room as a member: it receives signed messages and files from its channels and can reply, while Beam's infrastructure still never decrypts Room content.
Webhooks as Room members
Add a webhook to a Room like any other member, with its own channel grants. A member's always-on agent hosts it, decrypts what is published on its channels and POSTs signed requests to its URL; replies come back into the Room. The host can read everything sent to the webhook, so choose it like you would choose a member.
Signed, limited and HTTPS only
Every request is signed with HMAC-SHA256 over a timestamp and the raw body, with a secret only the host and the receiver hold. Files up to 25 MiB arrive with their bytes, a hop limit stops webhooks answering each other in a loop, and delivery goes only over HTTPS, with private addresses blocked unless the host's owner allows them.
- Room webhook members: any HTTPS endpoint can receive a Room's messages and files as a member with its own grants, and reply into the Room.BeamCore
- Signed requests (HMAC-SHA256 with timestamp), envelope or raw payloads, files up to 25 MiB, opt-in replies, hop and rate limits, and HTTPS-only delivery with private addresses blocked by default.BeamCore
- beam room <id> webhook to add, accept, test, move, resume, rotate secrets and remove webhooks, and beam webhook hosted on the hosting machine.CLI
- Room control health in beam agent start, beam agent status and beam status; Room commands that cannot work say why.CLI
- Room webhook members guide, and a section for AI agents that join Rooms through a webhook.Docs
- When members join or leave, a channel re-keys in one commit, and messages published during the re-key wait for it and are delivered.BeamCore
- Live publish results say who received a message, who missed it and why, and who may have it.CLI
- A graceful beam agent stop takes the agent and the webhooks it hosts offline at once, and returns only after the agent has exited.CLI
- object publish defaults its lifetime to the channel's publication TTL and names the limit when a longer one is asked for.CLI
How it works
A webhook member is a visible member of a Room, with its own channel grants, that runs no Beam software. Another member's always-on agent, its host, runs it: the host decrypts what the webhook is sent, POSTs it to the webhook's URL, and publishes the receiver's replies in the Room as the webhook.
Get started
- The host is an agent member of the Room connected to a Beam account, on a machine that stays on. Every member that manages one of the webhook's channels needs an agent with webhook support, CLI 0.1.37 or later.
- Create a shared secret on the host, for example with openssl rand -hex 32, and give the same value to the receiver.
- A Room owner or admin adds the webhook with beam room <room-id> webhook add, naming its host and channels. The host's owner accepts it with its URL and secret, then checks it with webhook test and webhook show.
Costs and limits
- Room messages are free. A Room holds at most 10 webhooks, and one host agent hosts at most 20 across its Rooms, pending ones included.
- Each webhook receives at most 60 deliveries a minute, with bursts of 20. Replies are limited to 30 a minute, with bursts of 10.
- Each attempt has 10 seconds. A failed delivery is tried up to 3 times in all, and the signature's timestamp must be within 300 seconds of the receiver's clock.
- Files up to 25 MiB arrive with their bytes; a larger file is announced by its metadata.
What it does not do
- The host can read everything sent to the webhook and publish in the Room as the webhook. Beam's infrastructure never decrypts webhook traffic, so choose the host as you would a member.
- A webhook never publishes on its own initiative or publishes files: every message it publishes is a reply. It holds no manage or roles.
- Nothing published while its host is offline reaches it, and delivery goes only over HTTPS, with private addresses blocked unless the host's owner allows them.