Event Driven Orbs

Amp's orbs can now receive requests and react to events outside Amp.

That means an orb can wake up when CI fails on GitHub, when someone opens a Linear issue, when a monitor raises an alert, or when an event arrives from Discord. If it can send an HTTP request, it can wake an orb.

More Ways to Wake an Orb

GitHub issues are just one example. You can use the same pattern to:

• Investigate every CI failure on main and post the findings to Slack.
• Watch for new releases of your dependencies, then review the changes and open an upgrade PR.
• Start a fresh thread when someone opens a Linear issue, then comment with a fix or report.
• Turn a bug report from Discord into a reproduction and pull request.
• Resume a rollout when a deployment or security scan reports back.

The event decides when the orb wakes up. You decide what it does next.

From a GitHub Event to an Orb

Here is the whole setup. Start a thread in an orb for your repository and tell Amp which events to watch and what to do with them:

Amp turns that request into a project-specific plugin. It scopes the listener to the repository and events you asked for, verifies GitHub's signature, deduplicates deliveries, and starts a read-only orb thread with trusted event metadata.

Then Amp loads the plugin and registers its durable endpoint:

If the orb's GitHub token can administer repository webhooks, Amp connects the endpoint for you. In this case it could not, so Amp gave us one manual step without printing the private URL or signing secret into the thread:

A Wild Issue Appears

Once the webhook is active, someone opens issue #57:

GitHub sends the signed event to Amp. Amp verifies it and starts a fresh orb thread with the trusted repository, event, issue, and actor metadata. The issue itself remains untrusted input, not agent instructions:

The new thread inspects the current issue and relevant code, then reports what it found:

The typo is real, appears once, and only affects secondary menu text. Now the same workflow runs for every issue and pull request event while the original orb sleeps.

How It Works

Webhooks work through the Amp Plugin API. When you ask Amp to listen for an event, it creates a plugin in the orb and calls amp.createWebhook to register a durable endpoint for that thread. Then it loads the plugin and gives you the URL to connect to GitHub, Linear, Discord, or another service. If the orb already has access, Amp can connect it for you.

When a request arrives, Amp stores the event and wakes the orb. The plugin validates and filters the payload, then handles it using the instructions you gave Amp. The URL stays the same across plugin reloads and orb restarts, so the orb does not need to keep running while it waits.

React to Events However You Want

amp.createWebhook gives the plugin a handler, not a fixed workflow. That handler is ordinary TypeScript with access to the rest of the Plugin API. The handler can:

• Continue the owning thread with its context intact by appending the event to ctx.thread.
• Start a fresh thread in an orb with amp.getBuiltinAgent(...).createThread({ executor: 'orb' }).
• Keep durable state so it can react every time, or handle one matching event and then stop listening.

That is where the flexibility comes from. Tell Amp how you want to handle an event and it writes the handler that way. It can also call external APIs to post results back to Slack, Linear, GitHub, or wherever the work began. Return to the owning thread whenever you want to change the behavior.

The webhook URL is a credential. Keep it private, and tell Amp to remove it when you no longer need it.