Blog · · The Expose team
Webhooks for AI coding agents: one URL for every Amp thread
Give every AI coding agent the same webhook URL. An Expose webhook hub sends each Stripe, GitHub or Shopify event to all of them and catches up paused ones.
When several AI coding agents work on the same app, each of them needs the webhooks your app receives. A webhook provider sends each event to the URLs you registered with it, though, and every agent's sandbox gets its own tunnel. So either one agent gets the events and the others wait, or you keep registering new URLs.
An Expose webhook hub fixes that. It's a reserved subdomain that up to 10 Expose clients of your team share at the same time. You register its URL with the provider once, and every connected client gets every event, byte for byte, so signatures still verify. Each Amp thread can join the hub as a service in its orb. A thread that was paused gets the events it missed when it comes back.
Why webhooks and AI agents don't mix#
A tunnel connects one public URL to one local server. That works for one developer on one laptop. It stops working when the "developer" is three agents in three cloud sandboxes:
- Providers want a fixed URL. You register an endpoint in the Stripe, GitHub or Shopify dashboard, and it stays there. A new tunnel URL for every sandbox means a new endpoint for every sandbox, and you have to clean them up later.
- A URL belongs to one tunnel. With a reserved subdomain the URL stays the same, but only one client can hold it. The second agent that runs
expose sharewith the same subdomain gets an error. - Agents come and go. Sandboxes pause when they're idle and start again later. A webhook that arrives in between is lost, unless the provider retries it at the right moment.
- Agents can't click through a login. A sandbox runs commands without a terminal, so the tunnel has to start from a token, not from a browser login.
What a webhook hub changes#
| Reserved subdomain | Webhook hub | |
|---|---|---|
| Clients on the URL | One | Up to 10, across your team |
| Who gets a request | The one client | Every connected client |
A second expose share |
Refused, the subdomain is in use | Joins the hub |
| The provider's answer | Your app's response | 200 right away, or the first 2xx of a member |
| Events while nobody is connected | Lost | Stored for 24 hours |
| Hub members and your tunnel limit | Count against it | Don't count |
Hub mode is a setting of the reservation, so a plain reserved subdomain still refuses a second client. That keeps catching the common mistake of starting the same tunnel twice.
Set up a hub#
You need Expose Pro and the Expose client 4.5 or later.
- Create a hub. On the Webhooks page of your Expose dashboard, click New webhook hub and pick its URL. You can also turn a subdomain you already reserved into a hub with the webhook icon on the Domains page. An agent can do the same through the Expose MCP server with
expose.reserve_subdomainandhub: true. - Register the hub's URL with the provider, for example
https://hooks.eu-1.sharedwithexpose.com/webhooks/stripe. This is the last time you touch the provider's settings. - Run the same command wherever your app runs, on your laptop, a teammate's laptop or in an agent's sandbox:
expose share http://127.0.0.1:8000 --subdomain=hooks --server=eu-1
Every client that runs this joins the hub, and every webhook reaches all of them. Your teammates use their own tokens: every member of the team has the reservation.
Run it in every Amp thread#
Amp runs each thread in its own orb, a cloud sandbox with a copy of your repository. Orbs start long-running processes from .amp/services.yaml, so the hub can start with your app in every thread. Here's the service:
services:
webhooks:
command: >-
expose share http://127.0.0.1:8000
--subdomain=hooks --server=eu-1
--auth="$EXPOSE_TOKEN" --hub-member="$AMP_THREAD_ID"
port: 4040
portal:
title: Expose dashboard
What each part does:
--auth="$EXPOSE_TOKEN"passes your Expose token, which you store as an Amp secret namedEXPOSE_TOKEN. Services run without a terminal, so they can't log in through the browser. Since Expose 4.5.1,expose sharestops right away with a hint when it has no token, instead of waiting for a login.--hub-member="$AMP_THREAD_ID"gives each thread a stable member ID. When a paused thread starts again, the hub delivers the events it missed, oldest first.port: 4040is the port of the Expose client's local dashboard. Amp waits for it before it marks the service ready, and opens it as a portal. There you see every webhook with your app's real response.
The client has to be installed in the orb, so add the install command to .agents/setup:
command -v expose >/dev/null || curl -fsSL https://expose.dev/install.sh | sh
You don't have to write any of this yourself. Each hub's page in the dashboard has an Amp prompt tab with a prompt to paste into a thread. Amp adds the install to .agents/setup, asks you to store the token as a secret, adds the service and sends a test request. Every thread of the repository then joins the hub.
None of this is specific to Amp. Claude Code, Codex, Cursor or a CI job can join a hub the same way: run expose share with a token and a member ID.
Missed events, replays and duplicates#
The Expose server stores each hub request exactly as it arrived, with headers and body, for 24 hours and at most 500 events per hub. That's what makes catching up possible:
- Reconnect with the same member ID. A client that passes the same
--hub-member(orEXPOSE_HUB_MEMBER) as before gets every stored event since it first joined that it wasn't delivered. Without a member ID, everyexpose shareis a new member and only gets events while it's connected. - Replay a time window.
expose share --hub-replay=10masks for every stored event of the last 10 minutes, whether or not the client got them before. - Look at the events. Each hub's page lists its connected members and recent events. Agents read the same list with the
expose.list_hub_eventsMCP tool.
Two things to know when events arrive late:
- Signatures carry a timestamp. Most webhook SDKs reject a signature that's older than a tolerance. Stripe's libraries allow 5 minutes by default, and some providers' SDKs allow only seconds. When you replay an event from an hour ago, raise the tolerance in development.
- The same event can arrive twice. Retries and replays deliver an event again. Handle webhooks idempotently, using the provider's event ID or the
X-Expose-Hub-Eventheader the hub adds. Your production handler needs that anyway, because providers retry too.
What the provider gets back#
A provider sees one answer, even though several apps got the request. You choose which one in the hub's settings:
200right away (the default). The server stores the event, answers200and then delivers it to every member. This is what most webhooks need, and it's how relay services such as Hookdeck, Webhook Relay and smee.io work. It also means the provider doesn't retry, so the hub retries for you: a member that answers with something other than 2xx, or doesn't answer within 30 seconds, gets the event again after 2, 8 and 20 seconds.- The first 2xx of a member. The server waits for the members and returns the first response with a 2xx status, within a timeout you set (4 seconds by default). Use it for providers that read your response, such as Slack's URL verification, which expects the challenge back in the body. With no member connected, the provider gets a
503.
Signatures still verify#
Providers sign the raw body, and Stripe, GitHub, Shopify and the Standard Webhooks spec all verify that signature in your app. The hub forwards the body and the provider's headers unchanged, so your existing verification code keeps working.
The hub adds three headers: X-Expose-Hub-Event (the event's ID), X-Expose-Hub-Attempt and X-Expose-Hub-Received-At. The server removes these headers from incoming requests, so a visitor can't fake them.
Limits#
- Webhooks only. Hubs take HTTP requests up to 1 MiB. WebSockets and TCP shares can't be hubs.
- 10 members per hub, across your whole team. Hub members don't count toward your tunnel limit.
- The Expose client 4.5 or later. The older PHP client can't join a hub.
- One hub per subdomain. If different apps need different events, use a hub for each.
How this compares#
Webhook relays such as Hookdeck, Webhook Relay and smee.io also send one provider's events to several listeners, through a URL on their service and a CLI of their own. Tunnels like ngrok can pool several endpoints on one URL, but they balance the load, so each request reaches only one of them. Amp's own plugin webhooks give a thread a stable URL, but only the thread that registered it receives the events.
A webhook hub is the relay pattern built into the tunnel you already run. The provider talks to your reserved subdomain, the events reach your app's real routes, and each client's dashboard shows them with your app's responses, like any other webhook you test with Expose.
FAQ#
Can several developers receive the same webhook?#
Yes. Make the reserved subdomain a webhook hub, and every member of your team who runs expose share with it gets every request. Up to 10 clients can be connected at the same time.
Do I need to change my webhook handler?#
No. The request reaches your app with the same path, headers and body as it left the provider. You can use the added X-Expose-Hub-Event header to drop duplicates.
What happens when no agent is connected?#
The hub answers the provider with 200 and stores the event for 24 hours. A client that reconnects with the same --hub-member gets it then, and --hub-replay fetches it on demand.
Does it work with Claude Code, Codex or Cursor?#
Yes. Any agent that can run a command can join a hub: give expose share a token with --auth and a stable --hub-member. Amp's orbs are where it takes the least setup, because one prompt adds the service for every thread.
Which providers does it work with?#
Any provider that sends webhooks over HTTPS, including Stripe, GitHub, Shopify and Paddle. Our guides for Stripe, GitHub, Shopify and Paddle show where to register the URL.