Event types

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:

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. 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 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.