Event types

An event type is the string that identifies what happened, such as invoice.paid or pull_request.opened. Hooks reads it from the provider payload or from the endpoint’s source configuration and shows it on every stored event.

The event-type registry is a per-project catalog of those names. It is documentation and convenience, not a gate: an endpoint still accepts and delivers any event type, registered or not, so existing senders never break because a type was not declared.

What registration gives you

• A stable list of the types the project expects, with descriptions.
• An optional JSON Schema document describing each payload.
• Suggestions in the console when sending a test event or writing an event.type filter.
• A deprecation flag for types that are being retired without deleting their history.

Managing types

The console page is Workspace → Event types. Owners and admins can register, edit and deprecate; other roles can read the list; viewers have read-only access.

GET    /v1/event-types
POST   /v1/event-types
GET    /v1/event-types/{id}
PATCH  /v1/event-types/{id}
Authorization: Bearer hks_...

Reads require the endpoints:read scope; writes require endpoints:write and a project admin role.

Register a type

POST /v1/event-types
Content-Type: application/json

{
  "name": "invoice.paid",
  "description": "An invoice was paid in full.",
  "schema": {
    "type": "object",
    "required": ["id", "amount"],
    "properties": {
      "id": { "type": "string" },
      "amount": { "type": "number" }
    }
  }
}

Names use letters, digits, dots, underscores, colons and hyphens, start with a letter or digit, and are unique per project (case-sensitive). A duplicate returns 409 EVENT_TYPE_EXISTS.

Update or deprecate

PATCH /v1/event-types/evtp_...
Content-Type: application/json

{ "deprecated": true }

description and schema are replaced when present; send null to clear either. deprecated: false revives a type. The name is immutable, because events already reference it: register a new type instead of renaming.

Filters and test events

Both pickers read the registry lazily, so they work with an empty catalog:

• Send test event suggests registered names in the event-type field.
• Destination filters suggest registered names when the condition field is event.type.

Neither picker restricts what you can enter. Deliveries are not validated against the JSON Schema; schema enforcement stays with your sender or your consumers.