Automation

Let an outside event start the work

Webhooks in Brainwrite start a bot's task from an external HTTP request, using the same queued executor as routines. They arrive at a separate local receiver, 127.0.0.1:8800 by default, which exposes only a health route and secret hook routes. Bearer authentication is preferred, and a capability URL is available for senders that cannot set headers.

Download for Mac Read the docs

A new issue arrives

When an issue reaches this webhook, check it for duplicates, suggest labels and post a summary here.

Your Chief of Staff put a team on it

Nova· Chief of Staff
Dash· Triage bot
Atlas· Rigel, QA and Release Engineer

Issue #482 received through the webhook.
Likely duplicate of #455: same stack trace in checkout.
Suggested labels: bug, checkout.
Drafted a comment linking the two issues.

Done1 comment to approve before it posts: waiting for your yes.

An illustrated example. Your team works on your own files and apps.

Split scene: at 11:04 pm a SaaS founder works alone in the dark; at 7:04 am he has coffee with AI agents Atlas and Dash.

See it in the app

Webhooks in Brainwrite.

Webhooks page: a Website demo requests webhook for Keeper, active on this computer, with a copyable curl command that starts a task.

How it works

How Webhooks works.

01
Give the hook its own endpoint
Each webhook trigger gets a dedicated secret route on the local receiver, separate from any schedule.
02
Authenticate the sender
Send the secret as a bearer token so it stays out of URLs and most access logs. Use the capability URL only when the sender cannot set headers.
03
Reach it from outside, narrowly
To accept events from the internet, proxy only the webhook receiver through a narrowly configured relay or tunnel. Never expose the main harness port.
04
Follow the run
The event starts a queued task with a fresh context and a durable run receipt, the same as a routine run.

Good to know

The details.

A separate receiver

The receiver is not the Brainwrite API. It exposes health and secret hook routes and nothing else.

Loopback by default

On 127.0.0.1, only your own machine can reach the receiver until you deliberately put a tunnel in front of it.

Independent of schedules

A webhook can trigger a bot that has no schedule at all, and a routine needs no webhook.

Same executor, same receipts

Webhook runs use the same queued task executor as routines, so you get the same run receipts and notifications for work that needs attention.

The edges, plainly

Webhook deliveries are not hosted jobs. Brainwrite must be running on your Mac, or the receiver is not listening.
Accepting events from the internet needs a relay or tunnel that you set up and keep narrow.
A capability URL carries the secret in the address, so it is more likely to show up in logs than a bearer token.

Full reference in the documentation

Use cases

Jobs this feature does for you.

Works with

Apps it's often used with.

FAQ

Questions about Webhooks

Can a webhook trigger an AI agent?

Yes. In Brainwrite, a webhook starts a bot's task from an external HTTP request, using the same queued executor as routines. Each trigger has a dedicated secret route on a local receiver, and each run gets a fresh context and a durable receipt.

Is it safe to expose an AI agent webhook to the internet?

Expose as little as possible. The receiver listens on 127.0.0.1:8800 by default and offers only health and secret hook routes, not the wider Brainwrite API. Put only that receiver behind a narrowly configured relay or tunnel, never the main harness port, and prefer bearer authentication.

Do webhooks work when Brainwrite is closed?

No. Local webhook deliveries are not hosted jobs. Closing the desktop app stops the local receiver and executor, so events sent while it is closed are not picked up by that receiver. Keep Brainwrite running on the Mac that should receive them.

Should I use a bearer token or a capability URL for webhooks?

Use a bearer token when the sender can set headers. It keeps the secret out of URLs and most access logs. The capability URL exists for senders that cannot set headers, but because the secret is part of the address, it is easier to leak through logs.

Works well with