Event

Understand This First

• Protocol – event delivery systems rely on protocols for publishing, subscribing, and acknowledging events.
• API – events are often delivered through APIs (webhooks, streaming endpoints).

Context

At the architectural level, software systems need to communicate about things that happen. A user clicks a button. A payment is processed. A sensor detects a temperature change. A file finishes uploading. Each of these is an event: a recorded fact that something occurred at a particular point in time.

Events are fundamental to how modern software is structured. Rather than one component directly calling another (tightly coupling them together), the component that detects something simply announces it as an event. Other components listen for events they care about and react accordingly. This pattern, called event-driven architecture, is how most interactive applications, distributed systems, and real-time pipelines are built.

In agentic coding, events are everywhere. When an AI agent completes a tool call, that’s an event. When a webhook fires to notify your system of a change in a third-party service, that’s an event. When a user submits a form that triggers an agent workflow, that’s an event.

Problem

One part of your system knows something happened, and other parts need to react to it. But you don’t want the sender to know about every receiver, because that creates fragile, tightly coupled code. Every time you add a new receiver, you’d have to modify the sender. How do you let parts of a system communicate about what happened without binding them tightly together?

Forces

• Decoupling vs. traceability: Events let components evolve independently, but tracing the chain of cause and effect through an event-driven system can be difficult.
• Flexibility vs. complexity: Adding new reactions to an event is easy (just add a listener), but understanding the full set of behaviors triggered by one event requires knowing all listeners.
• Timeliness vs. reliability: Events can be processed immediately (in-process) or queued for later (in a message broker), trading latency for durability.
• Simplicity vs. ordering: In simple systems, events arrive in order. In distributed systems, events may arrive out of order, duplicated, or not at all.

Solution

Model significant occurrences as events: immutable records of facts. An event typically includes:

• What happened: A clear name like OrderPlaced, UserSignedUp, or TemperatureExceeded.
• When it happened: A timestamp.
• Relevant data: The details needed to understand or react to the event (the order ID, the user’s email, the temperature reading).

Components that detect occurrences publish events. Components that need to react subscribe to the events they care about. The publisher doesn’t need to know who is listening; the subscriber doesn’t need to know who published.

In small applications, events can be simple function callbacks or in-process event buses. In larger systems, events flow through message brokers (like Kafka, RabbitMQ, or cloud services like AWS EventBridge) that provide durability, ordering guarantees, and the ability to replay events.

A critical design choice is the difference between events and commands. An event says “this happened”; it’s a fact, stated in past tense. A command says “do this”; it’s a request. Keeping this distinction clean makes event-driven systems much easier to reason about.

How It Plays Out

A team builds an e-commerce system. When an order is placed, the system publishes an OrderPlaced event. The billing service listens and charges the customer. The inventory service listens and reserves the items. The notification service listens and sends a confirmation email. None of these services know about each other; they only know about the event. When the team later adds a loyalty-points service, they simply subscribe it to OrderPlaced without modifying any existing code.

An AI agent integration uses webhooks to receive notifications from a third-party service. Each webhook delivery is an event. The agent’s handler must cope with the realities of distributed events: the same event might be delivered twice (requiring idempotent handling), events might arrive out of order (requiring the handler to check timestamps or sequence numbers), and events might be lost (requiring periodic reconciliation).

Consequences

Event-driven design decouples producers from consumers, making systems more flexible and extensible. New behaviors can be added without modifying existing components. Events also create a natural audit trail, a log of what happened and when, which is valuable for debugging, compliance, and analytics.

The costs are real. Debugging event-driven systems is harder because cause and effect are separated in both code and time. Understanding the full behavior of the system requires knowing all subscribers. Event ordering, duplication, and delivery guarantees add complexity that doesn’t exist in simple function calls. And poorly designed event systems can create cascading chains of events that are nearly impossible to follow.

Related Patterns

• Depends on: Protocol — event delivery systems rely on protocols for publishing, subscribing, and acknowledging events.
• Depends on: API — events are often delivered through APIs (webhooks, streaming endpoints).
• Contrasts with: Determinism — event-driven systems are typically nondeterministic in their ordering and timing.
• Enables: Concurrency — events are a natural way to structure concurrent, asynchronous work.
• Refined by: Side Effect — an event is a record of a fact; the side effects happen in the subscribers that react to it.