Events

What an event is

An event is any operation, alert or notification your system needs to deliver reliably, whatever the state of the network. It is the core primitive of wede: you send an event, and wede delivers it through the channel that the zone state and your continuity mode allow. An event can come from anywhere in your system: a dispatcher, a field team, a payment terminal or a request from one of your own customers.

Send an event

POST /v1/events

curl -X POST https://api.wede.pt/v1/events \
  -H "x-wede-api-key: wede_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cardiac_arrest",
    "vertical": "healthcare",
    "priority": "critical",
    "idempotency_key": "amb07-2026-09-26-0001",
    "payload": { "unit": "AMB-PT-07", "patient_ref": "P-1042" },
    "metadata": { "zone_id": "zone_hospital_evora" }
  }'

Field	Required	Description
`type`	Yes	An active event type of your catalog for this vertical, for example `cardiac_arrest` (see below)
`vertical`	Yes	A vertical active in wede. See Verticals
`priority`	No	`low`, `normal`, `high` or `critical`. Without it, the type’s default priority applies (`normal` when the type has none)
`idempotency_key`	Yes	1 to 128 characters, unique per operation
`payload`	Yes	JSON object with your operation data
`metadata`	No	`zone_id`, `operator_id`, `sdk_version`, `offline_generated_at` (ISO 8601), `connectivity_state_at_generation`
`destination`	No	One-off recipient for this delivery: `phone`, `email` or `device_id`. Used for this delivery only: over the fallback channels it is kept encrypted with your organisation’s key while the delivery runs and removed when it ends, never kept with the event

Unknown top-level fields are ignored. Set metadata.zone_id to the code of one of your zones: wede uses that zone’s connectivity state to decide how the event is delivered. Only zones linked to your organisation are resolved: a zone code that is not yours is ignored and the event is stored without a zone. An event without a zone is handled as online. Response 202:

{
  "event_id": "0ee3dfbe-1234-4bcd-9678-ef90ab12cd34",
  "idempotency_key": "amb07-2026-09-26-0001",
  "status": "pending",
  "environment": "production",
  "channel_selected": "rest_full",
  "request_id": "req-4f9a"
}

channel_selected is how the event reached wede, which is always rest_full for API submissions. The channel that actually delivered the event is channel_used on the event and channel in the event.delivered webhook.

Event types

An event’s type is an event type of your catalog: your organisation’s own vocabulary, organised by vertical and category, with lowercase codes such as cardiac_arrest or delivery_confirmed. wede pre-loads a starting catalog for each of your verticals; your administrators keep what fits, add their own types and deactivate the rest, in the dashboard (Catalog). Each type says whether the event needs a field team (requires_teams), which equipment or qualifications resolve it, and its default priority. Types that need nobody are delivered and recorded; types that need a team enter dispatch. Read the catalog with GET /v1/catalog. wede looks for an active type with that code in your catalog for the event’s vertical. Anything else returns 422 unknown_event_type, with the accepted codes in known_types. The response of POST /v1/events carries dispatch.status: queued or manual when the type sends a team, not_dispatchable with reason: type_does_not_require_teams when it does not, off when your organisation has no teams module, sandbox in sandbox. wede staff roles never see your types, categories, payload or metadata: only the vertical, priority, channel, timestamps and whether the type sends a team.

Priorities

Priority	Effect on delivery
`critical`	In a `degraded` zone, recorded as `rest_compressed`. In the fallback cascade, each channel gets more attempts before wede moves to the next
`high`	In a `degraded` zone, recorded as `rest_compressed`
`normal`	Standard delivery
`low`	Standard delivery

Priority is also used when wede scores teams for a dispatch. See Score engine.

Statuses

Status	Meaning
`pending`	Accepted and not delivered yet. In practice this is an event queued for store-and-forward (`channel_used: "queued_offline"`) or an event whose delivery is still in progress
`completed`	Delivered: online (`rest_full` or `rest_compressed`), through any channel of your cascade, or reconciled from the store-and-forward queue. The same applies to events accepted by Sync once they are delivered
`failed`	wede could neither deliver the event nor queue it for store-and-forward

The event status is the delivery status. If you use the optional teams and dispatch module, the outcome of a mission is tracked on the mission itself and never changes the status of the event. Every change is written to the event lifecycle, returned by GET /v1/events/:event_id as lifecycle entries with status, channel, note and timestamp.

Channels

channel_used is one of rest_full, rest_compressed, sms, voice, satellite, lora, edge or queued_offline. See offline-first architecture for what each channel means. Delivery outcomes are also sent as webhooks: event.delivered carries { event_id, status: "completed", channel, attempts }, event.failed carries the same fields with status: "failed" and error, and event.status_changed is sent with status: "pending" when an event is queued for store-and-forward.

Idempotency

idempotency_key is required. Sending the same key again returns 409 duplicate_event and never creates a second event, so retries are always safe. Choose keys that identify the operation, not the API call:

Your internal ID: order-29841-confirmed
Entity, date and sequence: amb07-2026-09-26-0001
A UUID generated when the operation is created: 550e8400-e29b-41d4-a716-446655440000

The same key is also checked against events received through Sync, so an operation sent online and later in a batch is stored once.

Payload minimisation

When an event becomes completed, wede clears the stored payload ({}) and keeps only identifiers, type, channel and lifecycle. Keep in your own systems any payload data you need after delivery.

Environments

Every event is stored with the environment of the credential that created it: production for wede_live_ keys and sessions, sandbox for wede_test_ keys. Sandbox events are never sent to a real provider: delivery is simulated with the same channel decision as production and recorded on the event with lifecycle notes that start with sandbox:. A simulated delivery ends completed (with its payload cleared), exactly as in production. Sandbox events never count toward usage or billing. An API key only reads events of its own environment. A session reads production by default and can pass environment=sandbox. The same idempotency_key can exist once in each environment.

Validation errors

Status	Code	When
`422`	`invalid_payload`	The body does not match the schema (details in `details`)
`422`	`unknown_vertical`	The vertical is not active in wede
`422`	`unknown_event_type`	The type is not an active type of your catalog for this vertical. `known_types` lists accepted codes
`409`	`duplicate_event`	The `idempotency_key` was already used in this environment
`403`	`forbidden`	The credential cannot write events

Examples by vertical

The types below are examples of codes from a tenant’s catalog; the first of each vertical is pre-loaded by wede, the others show what a tenant adds.

Healthcare
Banking
Logistics
Telecom
Government

{
  "type": "cardiac_arrest",
  "vertical": "healthcare",
  "priority": "critical",
  "idempotency_key": "icu-ward3b-2026-09-26-001",
  "payload": { "patient_ref": "PT-9821", "ward": "3B", "nurse_call": true },
  "metadata": { "zone_id": "zone_hospital_evora" }
}

{
  "type": "payment_offline",
  "vertical": "banking",
  "priority": "high",
  "idempotency_key": "pos-ng-042-20260926-0187",
  "payload": { "terminal_id": "POS-NG-042", "amount": 45000, "currency": "NGN" },
  "metadata": { "zone_id": "zone_lagos_mainland" }
}

{
  "type": "delivery_confirmed",
  "vertical": "logistics",
  "priority": "normal",
  "idempotency_key": "ord-29841-delivered",
  "payload": { "order_id": "ORD-29841", "driver_id": "DRV-KE-019" },
  "metadata": { "zone_id": "zone_nairobi_west" }
}

{
  "type": "site_power_failure",
  "vertical": "telecom",
  "priority": "critical",
  "idempotency_key": "bts-ae-112-20260926-001",
  "payload": { "site_id": "BTS-AE-112", "cause": "power_failure" },
  "metadata": { "zone_id": "zone_dubai_south" }
}

{
  "type": "alert",
  "vertical": "gov",
  "priority": "critical",
  "idempotency_key": "civil-maputo-norte-20260926-001",
  "payload": { "alert_type": "flood_warning", "severity": "red" },
  "metadata": { "zone_id": "zone_maputo_norte" }
}

List and read events

curl "https://api.wede.pt/v1/events?status=pending&limit=50" \
  -H "x-wede-api-key: wede_live_YOUR_KEY"

Filters: status, type, category (the code of a category of your catalog), vertical, zone_id, undispatched, legacy_type, limit (default 50, maximum 200) and cursor (the opaque next_cursor of the previous page). Sessions can also pass environment. undispatched=true returns only events whose type sends a team and that have no active mission (no mission, or only missions that ended FAILED): this is the dispatch queue used by the optional teams module. legacy_type=true returns open events sent before 8 October 2026 with a type that is not in your catalog. The response is { data, next_cursor, total_count }, where each item has event_id, type, category, category_name, requires_teams, vertical, priority, status, channel_used, created_at, updated_at, zone_id and environment. GET /v1/events/:event_id returns the event with its lifecycle.

Introduction

Core Concepts

Examples by Vertical

What an event is

Send an event

Event types

Priorities

Statuses

Channels

Idempotency

Payload minimisation

Environments

Validation errors

Examples by vertical

List and read events

​What an event is

​Send an event

​Event types

​Priorities

​Statuses

​Channels

​Idempotency

​Payload minimisation

​Environments

​Validation errors

​Examples by vertical

​List and read events

What an event is

Send an event

Event types

Priorities

Statuses

Channels

Idempotency

Payload minimisation

Environments

Validation errors

Examples by vertical

List and read events