# Event types

Your catalog of webhook events, each with a description and versioned JSON Schemas.

An event type names something that can happen in your product, such as `order.shipped`, `invoice.paid` or `user.deleted`. The catalog is what customers subscribe to and what Ensue validates every send against.

## Naming

Use `noun.verb` names, lowercase, with dots to group related events: `order.created`, `order.shipped`, `order.refunded`. Customers can then subscribe to all events at once or to just the ones they need.

## Create an event type

In the dashboard open **Event types → New event type**, or:

```bash
curl -X POST https://api.getensue.com/v1/event-types \
  -H "authorization: Bearer ens_<key>" -H "content-type: application/json" \
  -d '{
    "name": "order.shipped",
    "description": "An order has left the warehouse.",
    "schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "carrier":  { "type": "string" },
        "items":    { "type": "array", "items": { "type": "object" } }
      },
      "required": ["order_id"]
    }
  }'
```

Check a schema without saving it with `POST /v1/event-types/schema`. The dashboard can also infer a schema from an example payload.

## Schemas and validation

The `schema` is a [JSON Schema](https://json-schema.org). When you send an event, its `data` is validated against the **current version** of its type. If it does not match, Ensue answers `422` with the errors and sends nothing, so a bug in your app is caught at the source, not discovered by a customer.

Schemas also double as documentation: your customers see the same schema and an example payload for every type they can subscribe to.

## Versions

Add a version when the shape changes: `POST /v1/event-types/:id/versions` with a new `schema`. Sends use the **latest** version. Each message records the version it was sent with, so you can always tell what shape a customer received.

Keep changes **additive** where you can: add optional fields rather than renaming or removing, so existing customers' handlers keep working.

## Lifecycle

| Status | Meaning |
|---|---|
| `draft` | Still being designed. Only endpoints that **name** it receive it; `*` subscriptions skip it. |
| `active` | Live. |
| `deprecated` | Still delivered, but flagged so customers move off it. |
| `archived` | Retired. Sending it fails with `404 unknown_event_type`. Existing messages and history stay. |

Change a status with `PATCH /v1/event-types/:id`.

## Subscriptions

Each [endpoint](/dispatch/endpoints/) lists the event types it wants, or `["*"]` for every active and deprecated type (drafts must be named). The Event types page shows how many endpoints subscribe to each type and how many messages were sent in the last 24 hours, so you can see what is actually used before you change it.

> [!TIP]
> Send a first message to your own endpoint, as in the [Quickstart](/dispatch/quickstart/), before you announce a new event type to customers. The delivery shows exactly what they will receive.