Webhook and Event Connectors

What it is

The plumbing that connects an agent system to things that happen elsewhere: a public endpoint receiving callbacks from external systems, the verification and deduplication applied to them, the translation from a vendor's payload into something internal, and the outbound half that delivers notifications to other people's endpoints with its own retry and failure handling. Inbound, it is how an agent gets to be triggered by the world rather than only by a user typing.

Why it matters

Event plumbing is where an agent system acquires an unauthenticated public surface and an uncontrolled arrival rate at the same time. Senders retry on their own schedule, deliver at least once, occasionally deliver out of order, and sometimes replay. If each arrival starts an agent run that performs actions, then every one of those properties becomes a correctness problem with real-world effects: duplicated orders, repeated notifications, an action applied to a state that has already moved on. The payloads are also attacker-influenced text that will end up in a model's context.

Why it is not agent-to-agent communication

A sending system has no idea an agent exists. It emits a notification about something that happened in its own domain, on its own schedule, with no shared task identity, no capability negotiation, no way to be asked a question, and no interest in the outcome. All of the semantics have to be supplied on the receiving side: deciding what the event means, whether it warrants work, and what to do if the work fails. A peer agent participates in a conversation about a task; an event source announces a fact and moves on.

Key decisions

• Whether the handler does the work or only accepts it. Acknowledging quickly and queueing is almost always right: an agent run is far longer than any sender's delivery timeout.
• How a sender is verified — a signature over the raw body, a client certificate, a signed token, network origin — and what tolerance is allowed for clock skew and key rotation.
• The deduplication key and the window it holds for. Senders retry; some retry for days, and a window shorter than that is a window that does not work.
• What ordering you actually require, since most senders guarantee none. Where order matters, it is usually recoverable from a version or timestamp in the payload rather than from arrival sequence.
• Whether the event payload is trusted as fact or treated as a notification to be confirmed by reading the sending system's current state.
• Admission control on the inbound side: what happens when a burst arrives, and which events are allowed to start an agent run at all.
• For the outbound half: delivery semantics, retry schedule, signature scheme, and where permanently undeliverable messages accumulate.

Failure modes

• The handler runs the agent inline, the sender times out at a few seconds, retries, and every retry starts another run doing the same work.
• The signature is computed over a re-serialised body rather than the exact bytes received, so verification fails for payloads whose key ordering or whitespace differs.
• No deduplication exists, an at-least-once delivery arrives twice, and the effect is applied twice.
• A backlog is released after an outage and ten thousand events start ten thousand concurrent runs, exhausting model quota and downstream capacity at once.
• Event content reaches the model's context unmarked, and an attacker who can put text into the sending system can direct the agent.
• A signing key is rotated at the sender, verification begins failing, and the events are rejected silently because a rejected delivery looks identical to no delivery.
• An old signed delivery is replayed, with no timestamp check or nonce store, and is processed as new.
• Two updates for the same entity arrive out of order and the earlier one is applied last, leaving the system holding a state the sender abandoned.
• Outbound delivery retries forever against a dead endpoint with no dead-letter path, and the queue becomes the outage.

Related capabilities

• A2A and Agent Communication — the conversational counterpart this is not
• Tool Timeout and Retry — repeat safety, which at-least-once delivery makes mandatory here
• Tool Rate Limiting — admission control when a backlog releases at once
• Credential and Secret Management — custody and rotation of signing keys
• Tool Result Normalization — marking payload text as content before it reaches a model

Applies: Production readiness · Design questions