> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sailhouse.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

Events are the primary concept on Sailhouse. The container, envelope, metaphor of choice for your data.

They are JSON objects that get sent to a topic. You can't send an event to multiple topics, but you can send multiple events with the same data to multiple topics (although, that is likely an anti-pattern).

## Using events

<CardGroup cols={2}>
  <Card title="Learn how to send events" icon="rocket" href="/guides/sending-events">
    Get up to speed on sending events on Sailhouse.
  </Card>

  <Card title="Receive push events" icon="envelopes-bulk" href="/guides/receiving-push-events">
    Learn how to build handlers to securely process events sent from Sailhouse.
  </Card>
</CardGroup>

### Limitations

For non-enterprise customers, there is a maximum event size of **4mb** applied. However, if you're hitting this limitation it's likely an anti-pattern.

### Metadata

Events can have metadata attached to them. For example [attaching trace-ids](/observability/tracing), or bundling publisher information.

It's used by [cron jobs](/guides/cron-jobs) to populate information about the triggered cron.

## Understanding events

### Terminology

To help clear things up, here's a list of the common

* **Asychronous** - Processing in the background, in a non-blocking way
* **Event-driven** - An application design which does most of it's logic asychronously in response to logical events
* **Event** - A single package of data, sent to a topic

### Commands vs Events

When it comes to building event-driven applications, you'll probably come across the concepts of **Commands** and **Events**.

Sailhouse is a flexible platform enabling event-driven behaviours. At it's core, it enables any publish / subscribing pattern, and most real-world applications will have a blend of both.

#### Commands

Commands are a way of instructing behaviour in an application - where the publishing of which is directly triggering specific behaviour.

Think of a topic such as `backup-users`, which triggers a specific operation. Unlike events which notify about something that has happened, commands explicitly tell your system to do something.

Common command patterns include:

* User actions: `send-email`, `process-payment`, `generate-report`
* System operations: `backup-database`, `clear-cache`, `sync-inventory`
* Scheduled tasks: `daily-cleanup`, `refresh-analytics`

A typical command payload should contain all the necessary information for the operation to be performed:

```json theme={null}
// send-email
{
  "recipient": "user@example.com",
  "template_id": "welcome_001",
  "variables": {
    "user_name": "Jane Smith",
    "activation_link": "https://example.com/activate/abc123"
  }
}
```

#### Events

Events represent something that has happened in your system. Unlike commands which instruct specific behaviour, events are notifications that other parts of your system can react to.

For example, a topic like `user-created` indicates that a new user has been registered. Multiple services might be interested in this event:

* An email service could send a welcome message
* A analytics service could update user metrics
* A notification service could send a slack message to let you know someone has signed up

This decoupled nature of events means your system becomes more maintainable and scalable - new functionality can be added by simply subscribing to existing events, without modifying the original publishing code.

Here's what a typical event payload might look like:

```json theme={null}
// user-created
{
  "user_id": "usr_789xyz",
  "email": "jane@example.com",
  "signup_source": "web"
}
```