This post is part of Working with events, a series about messages in distributed systems.

The previous post was about how messages travel and how consumers read them. This one is about the story itself: what an event is for, how it will be consumed and how much of the story goes into the message.

There are two parts. The first goes through three questions to ask before you design an event: its purpose, its consumption model and its content. The second takes a closer look at the third question, through the problems that come up again and again: fields nobody should have added, events that carry everything, events that carry nothing, and stories spread over too many topics.

One thread runs through both parts: whose story the event tells, and who it is for.

Three questions before you design an event

I try to stay away from dogma here. You will find people telling you, book in hand, that there are exactly this many kinds of events and that everything else is wrong. If you talk to people with very firm positions you will have plenty of time to argue, and you will not reach any conclusion, because the answer is always the same: it depends.

What does help is having three axes in mind when you design an event. You could slice them differently, but these three work well:

  • Purpose: what is the event for?
  • Consumption model: how will it be consumed, and for how long?
  • Content: what should it carry?
Purpose Consumption model Content
Domain events Volatile Notification events
Integration events Durable Event-carried state transfer
Trigger events? Replayable Summary events
Event sourcing

Purpose: whose story, and for whom

People usually talk about domain events, integration events and even trigger events.

Trigger events may sound strange, but a webhook is, by definition, an event: something happened, and you are being told. It just travels over HTTP instead of through a broker. A webhook is a bit of a trompe-l’oeil, because what it is used for is firing something on the other side. Cause and effect, as Salvador Madrid put it. Most of the time you can forget about this category, but it is a good puzzle to think about.

So the usual distinction is between domain events and integration events, and in Domain-Driven Design both terms have a precise meaning. A domain event records something that happened inside a domain model, and it matters to other parts of the same bounded context. Very often it never even leaves the service; there is a post about that later in the series. An integration event is published for other contexts to hear: other teams, other services, other companies.

Knowing the strict meaning helps, but I prefer to turn the distinction into a question: which story do you want to tell, and to whom?

At a previous company, one of the things our customers valued most was that we gave them the same integration mechanisms we used ourselves. We did not have public and private APIs; we had APIs. And we did not have internal and external events; we had events, and it did not matter whether another team or another company consumed them. It meant we spoke the same language everywhere. I am old enough to remember the private APIs of Windows, which let some programs do things that others could not, simply because they knew those APIs existed.

In complex systems with other needs, very corporate ones for example, it can make all the sense in the world to draw those boundaries: domain events that are only consumed inside the domain, and a separate, curated set of events for everyone else. Mathias Verraes describes that approach as segregated event layers. But most of the time we end up talking about what are usually called integration events: events we want the outside world to hear. If I want to tell a story, I want people to hear it.

Neither option is wrong. Sometimes you will want to be strict about the difference, and sometimes you will prefer a simpler setup in which a single story is told both inside and outside. What matters is that it is a conscious decision, and that the whole team knows which one you made.

Consumption model: how long does the story last?

There are usually three consumption models:

  • Volatile. Thermostat readings. If one gets lost, nothing happens; another one arrives in a minute.
  • Durable. The classic RabbitMQ queue. Because you declared yourself as a consumer beforehand, the broker keeps the message until you consume it. If you go down, it waits for you.
  • Replayable. I do not even want to know who is consuming right now. I keep everything, and anyone can come back and revisit the story.

The previous post covered what it takes to go from durable to replayable. The point here is a different one, and Eduardo Ferro made it better than I could during the talk: think very hard, from the business point of view, about whether you can afford for this to work like a thermostat, because that is much easier. If, for example, every few events one of them is a snapshot of the current state, a consumer that only cares about the present can miss half the movie, catch the next snapshot and be up to date. Why would it care about what happened eight hours ago?

That means pushing hard to find the real business constraints, not the invented ones. People say “it has to be transactional” or “we cannot lose a single one”, and very often they do not know what they are asking for, or how hard life gets afterwards.

The opposite extreme bit us once. If you live only with replayable events and never define a retention period, one day a year has gone by and you are keeping a year of data. People with digital Diogenes syndrome will love it. For everyone else, it makes life much harder.

Content: how much of the story goes in the message?

There is no standard taxonomy for content either, but a few names help.

Notification events are, well, notifications. All events are, of course, but these are nothing else: “invoice 33 has been paid”, and that is the only piece of data I give you. Not the amount, not whose invoice it was, nothing. The minimum you need, and they tend to be very short.

Event-carried state transfer events exist to inform about a change of state in the system. They carry the identifier of the entity and the data that changed. “The customer changed their email” carries the customer id and the new email. That is not the same as “the customer changed their data” with the whole blob of the customer inside.

{ "type": "InvoicePaid", "invoiceId": "33" }
{ "type": "CustomerEmailChanged", "customerId": "c-981", "email": "ana@example.com" }

Sending only what changed and sending the whole state of the customer are both event-carried state transfer, and each has a price. A change like the new email only makes sense if the consumer received every previous change, in order. The full state of the customer, with a version number, tolerates lost or out-of-order messages. Sending the whole state of your own entity is not a fat event either: a fat event, as we will see below, carries other stories.

Summary events tell a whole story in one go. They look like fat events but they are something else, and they get their moment in the post about choreography and orchestration.

Notice that we are not talking about which one to use, because it depends. What you do have to weigh, as Eduardo pointed out, are sizes, volumes and scale; it is always a trade-off. If you put the whole state in, you can correlate very well what happened with what exists, and many processes become much simpler. With a notification event, on the other hand, you are still tied to the publisher, as he put it: to do anything useful you need to know who can give you more data, which domain owns it and where its endpoint is, and then go and ask.

A thin event makes the consumer call backNotification eventEvent-carried state transferBillingConsumerBilling APIBillingConsumerInvoicePaid #33GET /invoices/33InvoicePaid #33 + data
With a notification, the consumer has to find out who owns the data and ask for it. With event-carried state transfer, the data travels with the event.

His advice, which I share: go for the simple solution until it is shown that the next one is necessary. The same goes for the consumption model.

Sometimes it even makes sense to tell the same story with two faces: a notification event that makes gathering metrics easy, and an event-carried state transfer or a summary for other integration scenarios. Where is that extra complexity worth it? Maybe where the volumes are enormous, and consuming the bigger event in a place where a smaller one would do has a real cost. Spoiler: in very few places. Most of the time, favor the story you want to tell.

Event sourcing is storage, not communication

Event sourcing appears in the same list, but it is a different beast: it is not a pattern for communicating, it is a pattern for storing. It is an alternative way of persisting information.

When Eduardo asked me to explain it for those who did not know it, the short version was this: event sourcing takes the idea of replayable and turns it into a persistence mechanism. Instead of storing state in my tables (this customer, in this state, with this data), I store the events that, once processed, produce that state.

Eduardo came up with the clearest analogy. Your bank does not store your balance. It stores transactions: deposits, withdrawals, loans. If they get something wrong, they do not edit a field; they add another event, like the fee they decided to charge you. Diego Álvarez asked whether that means recomputing everything every time you want to know the balance. In principle, yes. In practice you keep snapshots, so that you do not replay everything every time, and projections, which are read models built from the events. But the source of truth is the full list of transactions. That is what you take to court.

The bank does not store your balanceEvents: the source of truthDeposited 100Withdrawn 30Fee charged 6Deposited 50Balance: 114a projectionreplay
With event sourcing, the source of truth is the list of events. The balance is a projection computed from them.

Event sourcing is the first lesson at show-off school. I mean it: it is a pattern with real uses, and it gets used, but when people get excited about distributed systems and Domain-Driven Design, and have just bought the right book, they want to solve everything with it. It is fascinating and it has serious challenges, starting with the fact that here there is no retention period at all. It does give you the free audit, though.

Whose story is it? Fat events, thin events and blurry boundaries

The three questions give you a frame, but the third one, content, is where most designs go wrong in practice. Nobody designs perfect events, in the same way that nobody designs perfect APIs. Salvador Madrid pointed out another reason during the talk: time itself changes things. Businesses evolve, and so do the stories they tell.

But some problems come up again and again, and most of them share a root: we forget whose story the event tells.

Blurry boundaries

How do you notice that the boundaries are not clear? Look at the reasons behind the changes to an event’s contract. If a change exists because “so-and-so came and asked me to add this field”, something is off. As the post about who owns the story argued, the publisher owns the story: consumers can ask, the owner decides.

It will happen, of course, that someone comes and asks for something. That is why I keep talking about narrative. If the story you want to tell makes sense, the event almost designs itself, and it becomes much easier to see which requests belong in it and which do not.

There will always be someone telling you: “It would be great if, when you publish the invoice-issued event, you also included how much this customer has been invoiced this month.” And you have to answer, politely, that it would be great for them, but it makes no sense for the event. “That is another story.”

Think of it on paper: nobody prints the customer’s monthly statement on the back of every invoice. They are two documents because they tell two different stories, and an event that carries both makes the same mistake.

Fat events

The first classic antipattern is the fat event, which carries a huge amount of information. Sometimes the infrastructure stops you. Azure Service Bus, for example, does not accept messages over 256 KB in its standard tier, and even that limit is generous. “200 KB is crazy,” as Matías Nabarro said about a single message. Other brokers let you send megabytes, and then nothing stops you.

Imagine an event that says “a new price catalog has been uploaded”. Publishing that event with the location or the identifier of the uploaded file is not the same as putting the whole catalog inside the event. That kind of thing happens. The first option even has a name in Enterprise Integration Patterns: the claim check, a ticket that lets whoever needs the data go and pick it up.

{
  "type": "PriceCatalogUploaded",
  "catalogId": "2026-10",
  "location": "s3://catalogs/2026-10.json"
}
{
  "type": "PriceCatalogUploaded",
  "catalogId": "2026-10",
  "products": [
    { "sku": "A-100", "name": "…", "price": 12.5, "stock": 40, "images": ["…"] },
    "… 40,000 more …"
  ]
}

That is the most extreme example. A more common one looks innocent: “this invoice has been issued”, and inside it the invoice data, the customer data, the customer’s contact details for every possible circumstance and the last six shipments, because they came in handy.

The problem is not only size. Every field you add becomes part of the contract, and somebody will couple to it.

Thin events

Then there is the opposite, the thin event. The notification from the first part, “invoice 33 has been paid”, is useful precisely because it is small. But if all you ever give consumers is two pieces of data, they will be going back to your database, or to your API, every two minutes. There is no formula for the middle ground, because it is the trade-off between size and coupling we saw above, but a few heuristics help. Include what the story needs to be complete, with the values things had at that moment, like the price of a product when it was ordered. Carry identifiers for everything else. And leave out whatever belongs to someone else’s story.

Events that are born big stay big

Complexity always arrives by itself, because systems grow organically. And an event that is born big will hardly ever shrink. Shrinking it takes a lot of energy, because people start coupling to it, and the day you want to remove a field, someone tells you they were using it.

Complexity kills, as Eduardo Ferro summed it up. Start simple and grow from there.

How many storytellers?

Salvador raised a good question during the talk: does this conflict with the other classic debate, whether to have many small topics or a few big ones? If every different story goes somewhere else, are we creating too many tiny streams?

Metaphors always break at some point, but this one still helps. Having several topics can mean having several people each telling a different story, and that is fine. The problem is having several people each telling a part of the same story. At that point, as Salvador said, it becomes a Nolan movie.

Picture a warehouse, and one topic with every event related to it. Some consumers will decide to ignore some of those events, but the whole story the warehouse wants to tell is in that topic. Now imagine that you create one topic per origin: one per supplier that sends goods to the warehouse. How many minstrels are telling me this story? How many places do I have to connect to? It is the same idea as the orders topic in the previous post, where Orders tells every story about its orders in one place.

Time matters here, too. If the events of one warehouse go to a single topic with the same key, Kafka delivers them in the order in which they arrived. That is not necessarily the order in which they happened, but it is one order, and you hear the story consistently. As soon as the story is spread over several topics, the order in which you hear it can change.

One storyteller or severalOne topicOne topic per supplierWarehousewarehouseConsumerHeard: –WarehouseABCConsumerHeard: –
Events that travel through one topic with the same key arrive in one order. Spread the same story over several topics, and the consumer may hear it in a different order.

Eduardo added the dimension that, for me, closes the argument: the audience. If the audience has to join three topics to rebuild the story, that is hell. And there is no magic behind the scenes, no dwarves putting things back in order. Order only holds within a partition, as the previous post explained. By default, choose the simplest option. Complexity will arrive without you inviting it, and the later it arrives, the better.

Questions to ask

  • Is this event for your own domain, or for anyone who wants to listen?
  • Can the business live with this working like a thermostat?
  • Who needs the history, and for how long?
  • Does the consumer have enough to act without calling you back, and could the event be smaller without losing that?
  • Are you choosing the content for the story you want to tell, or for one specific consumer?
  • Do you need event sourcing, or do you only need to publish events?
  • Who decided that this field belongs in the event: the owner of the story or a consumer?
  • If this field were not there, would the story still be complete?
  • Is the event carrying data, or references to data?
  • Do consumers have to join several topics to understand a single story?
  • Are you splitting topics by story, or by a technical criterion such as origin?

Next in the series: the event contract, from the envelope and the name to how events evolve.