# Overview

Source: https://gokarla.io/docs/platform/events/overview

# Events

Karla generates events throughout the customer journey — order creation,
delivery, post-purchase issue resolution. Every event has a consistent shape
so the same plumbing (webhooks, notifications, analytics pipelines, AI agents)
works across sources.

This overview covers the shared concepts. For source-specific catalogues and
payload examples, see:

- [Shipment events](/docs/platform/events/shipments) — carrier
  event catalogue, groups, phases, direction, and the Shipment Events API.
- [Claim events](/docs/platform/events/claims) — events emitted by
  Resolve flows.

## Key concepts

Every event carries these fields. The first three apply to all sources; the
last two are shipment-specific refinements.

| Field         | Applies to     | What it is                                                                                   |
| ------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `source`      | all            | The top-level entity that generated the event (`shipments`, `claims`).                       |
| `event_name`  | all            | The specific thing that happened (`SUCCESSFULLY_DELIVERED`, `CLAIM_CREATED`).                |
| `event_group` | all            | The notification bucket. This is what fires your Klaviyo / webhook / email flow.             |
| `phase`       | shipments only | The lifecycle stage the parcel is in (`in_transit`, `delivered`, `returned`, …).             |
| `direction`   | shipments only | `merchant_customer` (forward) or `customer_merchant` (return). Can change the `event_group`. |

**How they combine**: one `event_name` always maps to exactly one
`event_group` (given a `direction`), which is the field you subscribe to.
`phase` is informational — use it to scope `ref` filters (see below).

:::tip Wire notifications to groups, not names
Filter on `event_group` when subscribing to webhooks or building Notify
flows — the groups already bundle events that should trigger the same
customer message. Filter on `ref` or `phase` when you need broader scopes
like "any in-transit event".
:::

## Ref pattern

The `ref` is a slash-separated identifier used when subscribing via
`enabled_events` on webhooks. Its shape depends on source:

- **Shipments**: `shipments/{phase}/{event_name}` — e.g.
  `shipments/delivered/SUCCESSFULLY_DELIVERED`.
- **Claims**: `claims/{action}` — e.g. `claims/created`.

Broader refs catch every event beneath them — `shipments/delivered` matches
every event in the `delivered` phase, `shipments` matches all shipment
events.

## Payload envelope

Every Karla event — regardless of source — follows this structure:

```jsx title="Standard event envelope"
{
  "source": "shipments|claims",
  "ref": "{source}/{phase|action|event_name}[/{event_name}]?",
  "version": 1,
  "triggered_at": "2024-01-29T14:48:47+00:00",
  "event_group": "shipment_in_transit|claim_created|...",
  "event_data": {
    // Source-specific data — see shipment events or claim events.
  },
  "context": {
    // Related entities and metadata: order, shipments, and claims.
  },
  "shop_slug": "your-shop-slug",
  "shop_id": "your-shop-uuid"
}
```

`event_data` is what typically gets exposed into your email templates when
using native integrations. `context` carries the full order / shipment /
claim objects so a downstream consumer never needs a second API call just to
know what the event refers to.

## Event filtering

When subscribing to events (webhooks, Notify integrations), use `ref` values
in `enabled_events`. Broader refs match more specific ones.

### All events

```json
{
  "enabled_events": ["*"]
}
```

### Filter by source

```json
{
  "enabled_events": ["shipments", "claims"]
}
```

### Filter by shipment phase

```json
{
  "enabled_events": ["shipments/delivered", "shipments/in_delivery"]
}
```

### Granular event filtering

```json
{
  "enabled_events": [
    "shipments/delivered/SUCCESSFULLY_DELIVERED",
    "shipments/in_delivery/OUT_FOR_DELIVERY",
    "claims/created"
  ]
}
```

### Common business cases

Mix levels freely — broad for most phases, granular where you need precision:

```json
{
  "enabled_events": [
    "shipments/delivered",
    "shipments/delivery_failed",
    "shipments/in_transit/DELAY_EXPECTED",
    "shipments/in_transit/SHIPMENT_DAMAGED",
    "claims"
  ]
}
```

## Third-party tools

We integrate with any third-party tool that accepts custom event creation via
its API. If the tool allows passing a custom attributes object, that object
follows the `event_data` shape documented per source.

If the tool does **not** support nested objects (e.g. some ESPs only accept a
flat key/value payload), Karla flattens each `event_data` variable onto the
root of the event body. For example, `event_data.tracking_number` becomes a
top-level `tracking_number` field on the payload the tool receives.

[Contact us](mailto:hello@gokarla.io) for help wiring Karla events into any
tool you already use.

## Related

- [Shipment events](/docs/platform/events/shipments) — catalogue,
  groups, phases, direction, `event_data`, and the Shipment Events API.
- [Claim events](/docs/platform/events/claims) — catalogue and
  `event_data` for Resolve.
- [Webhooks](/docs/guides/notify/webhooks) — subscribing to events over HTTP.
- [Notify integrations](/docs/guides/notify/disable-carrier-emails) — wiring
  events into Klaviyo, Brevo, HubSpot, etc.
- [API reference](/docs/api-reference) — endpoint specs.