# Agent events need delivery semantics Why local agents, hosted agents, and MCP clients need different event delivery contracts. Published: 2026-05-14 Updated: 2026-05-14 Canonical: https://watch.qordinate.ai/blog/webhook-vs-pull-delivery-for-agent-events Markdown: https://watch.qordinate.ai/blog/webhook-vs-pull-delivery-for-agent-events.md Image: https://watch.qordinate.ai/images/blog/webhook-vs-pull-delivery-for-agent-events.jpg Tags: - webhooks - pull delivery - agent runtimes ## Short answer Agent events need delivery semantics because different runtimes receive interrupts differently. Hosted agents usually want signed webhooks, local agents usually want pull delivery, and MCP is often better as the setup/control plane than the delivery plane. ## Key takeaways - A matched agent event carries a different contract than a raw source event. - Webhooks fit hosted backends that can expose stable HTTPS endpoints. - Pull delivery fits local agents that should keep localhost and home machines private. - MCP is excellent for creating and managing watches, while delivery may need a different path. - Delivery should be swappable without changing the user’s underlying intent. ## Why this matters Most infrastructure teams understand webhooks. A source system sends an HTTP request, the receiver verifies a signature, and the application handles the event. That model works well for hosted software. Agents complicate it. Some agents run in a cloud backend. Some run on a developer’s laptop. Some run inside a local OpenClaw workspace. Some receive control calls through MCP. Some can expose a webhook. Many need another route. If agent infrastructure treats every delivery problem as "just send a webhook," it misses the shape of the runtime. ## A matched event carries a different contract Raw source events are usually noisy. An inbox receives a message. A calendar event changes. A pull request updates. A ticket gets commented on. Most of those events do not deserve an agent turn. Agent delivery should usually happen after a match decision, not before. The receiving agent should get the event because it matched a user-defined condition, not because something happened somewhere. That distinction changes the payload. The event delivered to the agent should carry the original source context, the user intent it matched, and enough identity/channel information for the runtime to route it. Leave out provider implementation details the agent does not need. ## Hosted agents want push delivery If an agent product has a public HTTPS endpoint, push delivery is the most direct path. The infrastructure can send a signed payload as soon as a relevant event is found. Push delivery is good when the receiver is always online, centrally hosted, and easy to secure with standard webhook verification. It also maps well to queue-backed ingestion systems: receive, verify, enqueue, acknowledge. The operational questions are familiar: - What gets signed? - How long is the replay window? - What status codes trigger retry? - When does a delivery become dead? - How does the receiver dedupe retries? These are solved problems in web infrastructure. Agent companies should inherit that discipline instead of inventing a chat-shaped event protocol. ## Local agents want pull delivery Local agents live under a different trust boundary. A laptop can receive interrupts without exposing localhost to the internet. A user should not need ngrok for a normal proactive workflow. Pull delivery flips the direction. The local runtime makes an outbound request for pending matched events, handles them, and acknowledges what it accepted. This model has tradeoffs. It can lag behind a webhook. It needs a polling cadence, backoff, and pending delivery retention. In return, it fits the security and deployment model of local software much better. For a local agent, "poll for matched events" differs sharply from "poll every connected app." The app noise has already been reduced upstream. The local runtime only asks for events that survived the match layer. ## MCP is a control plane, not always a delivery plane MCP is excellent for giving an agent tools: create a watch, continue setup, list watches, pause, resume, delete. Delivery needs more care. Some MCP clients can call tools repeatedly and poll. Some were never designed as background workers. Some live inside products that already have their own webhook ingestion path. The clean separation is: - Use MCP to let agents manage intent subscriptions. - Use delivery channels to move matched events into the runtime. Sometimes one surface can handle both jobs. Often it cannot. ## Delivery should be swappable without changing intent The user’s intent should survive delivery changes. "Tell me when this happens" should mean the same thing whether the matched event lands in a hosted webhook, a local pull queue, or a future realtime channel. A watch can bind to a delivery channel without depending on it for meaning. Moving from local pull to hosted push should not require rewriting the condition. Boring architecture matters here. It lets developers start with a local demo, move into a hosted backend, and keep the user’s mental model stable. ## The future delivery contract is probably mixed Long-term agent systems will use multiple delivery modes at once. A customer support agent might receive customer escalations through a hosted webhook. The same user’s desktop assistant might pull personal inbox matches locally. A coding agent might register watches through MCP but receive urgent events through a product-specific inbox. The event layer can stay runtime-agnostic: preserve a durable condition, reduce noise, and deliver a matched event through the channel that fits the environment. Delivery semantics belong in the core design because they decide whether proactive agents feel native or bolted on. ## FAQ ### Should every agent event be delivered through a webhook? No. Webhooks are great for hosted agent products. Local agents and desktop assistants usually need pull delivery because the runtime can safely make outbound requests without exposing a public endpoint. ### What is pull delivery for agents? Pull delivery is a model where the agent runtime asks for pending matched events, handles them, and acknowledges what it accepted. It is useful for local or semi-local systems that cannot receive inbound webhooks. ### Where does MCP fit? MCP is best treated as a control plane for setup and management: create a watch, continue setup, list watches, pause, resume, and delete. Delivery can still happen through webhooks, pull queues, or another runtime-specific path. ### What should be inside a matched event payload? The payload should include the matched user intent, source-event context, routing identity, delivery id, and version. It should avoid leaking provider internals that the receiving agent does not need. ## Further reading - https://platform.openai.com/docs/codex/overview - https://docs.anthropic.com/en/docs/claude-code/hooks - https://support.claude.com/en/articles/14554922-claude-code-user-faq