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 — carrier event catalogue, groups, phases, direction, and the Shipment Events API.
Claim events — 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).

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:

{
  "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#

{
  "enabled_events": ["*"]
}

Filter by source#

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

Filter by shipment phase#

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

Granular event filtering#

{
  "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:

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

Shipment events — catalogue, groups, phases, direction, event_data, and the Shipment Events API.
Claim events — catalogue and event_data for Resolve.
Webhooks — subscribing to events over HTTP.
Notify integrations — wiring events into Klaviyo, Brevo, HubSpot, etc.
API reference — endpoint specs.