> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wede.pt/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> How events work in Wede

## What is an Event

An event is any operation, alert, or notification that your system needs to deliver reliably — regardless of connectivity conditions.

Events are the core primitive of the Wede platform. You send an event, Wede guarantees delivery through the best available channel.

## Event Structure

```json theme={null}
{
  "type": "EMERGENCY_DISPATCH",
  "priority": "critical",
  "vertical": "healthcare",
  "idempotency_key": "dispatch-2026-05-19-amb07-001",
  "payload": {
    "unit": "AMB-PT-07",
    "location": "Hospital Santa Maria, Lisboa"
  }
}
```

| Field             | Required | Description                                              |
| ----------------- | -------- | -------------------------------------------------------- |
| `type`            | Yes      | Event type — freeform string, uppercase recommended      |
| `priority`        | Yes      | `critical`, `high`, `normal`, or `low`                   |
| `vertical`        | Yes      | Industry vertical — see [Verticals](/concepts/verticals) |
| `idempotency_key` | Yes      | Unique key to prevent duplicate processing               |
| `payload`         | No       | Arbitrary JSON payload — your data, opaque to Wede       |
| `zone_code`       | No       | Target zone — routes to specific operational area        |

## Priority Levels

| Priority   | Description                           | Channel Behaviour                  |
| ---------- | ------------------------------------- | ---------------------------------- |
| `critical` | Immediate delivery required           | All channels attempted in parallel |
| `high`     | Fast delivery, minor delay acceptable | Primary + fallback channels        |
| `normal`   | Standard delivery                     | Primary channel with fallback      |
| `low`      | Best-effort delivery                  | Primary channel only               |

## Event Response

```json theme={null}
{
  "event_id": "0ee3dfbe-1234-abcd-5678-ef90ab12cd34",
  "status": "pending",
  "channel_selected": "rest_full",
  "created_at": "2026-05-19T10:00:00Z"
}
```

## Event Status

| Status           | Meaning                                        |
| ---------------- | ---------------------------------------------- |
| `pending`        | Accepted, awaiting delivery                    |
| `delivered`      | Successfully delivered                         |
| `failed`         | Delivery failed after all retries              |
| `queued_offline` | Queued for delivery when connectivity restores |

## Event Examples by Vertical

**Healthcare:**

```json theme={null}
{
  "type": "ICU_ALERT",
  "priority": "critical",
  "vertical": "healthcare",
  "idempotency_key": "icu-alert-2026-05-19-ward3b-001",
  "payload": {
    "patient_id": "PT-9821",
    "ward": "3B",
    "alert": "cardiac_arrhythmia",
    "nurse_call": true
  }
}
```

**Banking:**

```json theme={null}
{
  "type": "PAYMENT_DECLINED",
  "priority": "high",
  "vertical": "banking",
  "idempotency_key": "payment-decline-term042-20260519-001",
  "payload": {
    "terminal_id": "POS-NG-042",
    "reason": "connectivity_timeout",
    "amount": 45000,
    "currency": "NGN"
  }
}
```

**Logistics:**

```json theme={null}
{
  "type": "SHIPMENT_DELAYED",
  "priority": "normal",
  "vertical": "delivery",
  "idempotency_key": "shipment-delay-ord29841-20260519",
  "payload": {
    "order_id": "ORD-29841",
    "driver_id": "DRV-KE-019",
    "reason": "road_closure",
    "new_eta": "2026-05-19T16:30:00Z"
  }
}
```

**Telecom:**

```json theme={null}
{
  "type": "TOWER_DOWN",
  "priority": "critical",
  "vertical": "telecom",
  "idempotency_key": "tower-down-bts112-20260519-001",
  "payload": {
    "site_id": "BTS-AE-112",
    "location": "Dubai — Al Barsha",
    "cause": "power_failure",
    "affected_subscribers": 8400
  }
}
```

**Government:**

```json theme={null}
{
  "type": "CIVIL_PROTECTION_ALERT",
  "priority": "critical",
  "vertical": "gov",
  "idempotency_key": "civil-alert-maputo-norte-20260519",
  "payload": {
    "zone": "zona_norte_maputo",
    "alert_type": "flood_warning",
    "severity": "red",
    "population_affected": 34000
  }
}
```

## Listing Events

```bash theme={null}
curl https://api.wede.pt/v1/events \
  -H "x-wede-api-key: wede_live_YOUR_KEY"
```

## Idempotency

Always provide a unique `idempotency_key` per logical event. If the same key is submitted twice, Wede processes it once and returns the original response.

Good idempotency keys include:

* Timestamp + entity + sequence: `dispatch-2026-05-19-amb07-001`
* Your internal event ID: `internal-evt-id-84729`
* UUID: `550e8400-e29b-41d4-a716-446655440000`