# Webhook Events

## Dynamic event types

Event types in Apiera are **dynamic**. New event types may be added at any time as the platform evolves.

Use the event types API to discover what's currently available:


```bash
curl https://api.apiera.io/v1/webhook-event-types \
  -H "Authorization: Bearer {token}"
```

Each event type includes:

| Field | Description |
|  --- | --- |
| `type` | Event identifier string (e.g. `product.created`). |
| `version` | Semantic version (e.g. `V1`). |
| `description` | Human-readable explanation of when this event fires. |
| `templateJson` | JSON schema showing the payload structure with placeholder UUIDs. |
| `deprecatedAt` | If set, the event type is deprecated. |
| `sunsetAt` | If set, the date after which the event type will no longer fire. |


Always use the event types API as the source of truth. New event types may be added at any time as new services and
resources are introduced.

## Naming convention

Event type strings follow a consistent pattern:


```
{resource}.{action}
{resource}.{sub-resource}.{action}
```

**Actions:**

- `created` - A new resource was created.
- `updated` - An existing resource was modified.
- `deleted` - A resource was permanently removed.
- `linked` - A sub-resource was associated with its parent.
- `drafted` / `published` / `unpublished` / `archived` / `unarchived` / `removed` / `restored` - Lifecycle transitions.


## Payload structure

All payloads are **thin**. They contain only the UUIDs needed to fetch current state from the REST API. There are no
before/after values or embedded resource data.

### Payload-to-endpoint mapping

Every payload maps 1:1 to a REST endpoint. The UUIDs in the payload are the path parameters. No guessing required.

The following examples illustrate how different levels of resource nesting produce different payload shapes:

**Top-level resource event** (`product.created`, `product.published`, etc.):


```json
{
  "productUuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

Maps to: `GET /v1/products/{productUuid}`

**One-level sub-resource event** (`product.attribute.linked`, `product.asset.linked`, etc.):


```json
{
  "productUuid": "550e8400-e29b-41d4-a716-446655440000",
  "productAttributeUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
```

Maps to: `GET /v1/products/{productUuid}/attributes/{productAttributeUuid}`

**Two-level sub-resource event** (`product.attribute_term.linked`, etc.):


```json
{
  "productUuid": "550e8400-e29b-41d4-a716-446655440000",
  "productAttributeUuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "productAttributeTermUuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}
```

Maps to: `GET /v1/products/{productUuid}/attributes/{productAttributeUuid}/terms/{productAttributeTermUuid}`

This pattern is consistent across all resources and services. The payload always contains exactly the UUIDs needed to
construct the corresponding REST API path.

## Deprecation and sunset

Event types can be **deprecated** and eventually **sunset**:

- **Deprecated** - The event type still fires but is planned for removal. The `Deprecation` header is included in
deliveries. Migrate to the replacement event type.
- **Sunset** - After the sunset date, the event type stops firing entirely. The `Sunset` header indicates the cutoff
date.


Check the `deprecatedAt` and `sunsetAt` fields in the event types API to stay ahead of changes.