Quickstart

This guide takes you from your API keys to a production integration. Every step uses the sandbox first, so nothing reaches a real recipient and nothing counts toward usage or billing.

1. Get your API keys

Every tenant has two kinds of API key:

Prefix	Environment	Use
`wede_live_`	`production`	Real operations
`wede_test_`	`sandbox`	Development and tests. Delivery is simulated, never sent to a real recipient

A user with the company_admin role manages keys in Settings in the wede dashboard. A key is shown in full only once, when it is created or rotated: store it straight away in your secret manager or environment variables. To create the first key of an environment with the API, sign in as a company_admin and call POST /v1/tenant/api-keys with { "environment": "sandbox" } or { "environment": "production" }. See Authentication for rotation.

API keys are server-side credentials. Never put one in a browser, a mobile app or a public repository. Apps sign the user in and use a session token instead.

export WEDE_API_KEY=wede_test_...

2. Send your first event

curl -X POST https://api.wede.pt/v1/events \
  -H "x-wede-api-key: $WEDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "EMERGENCY",
    "vertical": "healthcare",
    "priority": "high",
    "idempotency_key": "qs-0001",
    "payload": { "unit": "AMB-07", "reference": "INC-0001" }
  }'

Field	Required	Description
`type`	yes	An active event type of your catalog for this vertical (for example `cardiac_arrest`; wede pre-loads a set per vertical, read it with `GET /v1/catalog`). Anything else returns `422 unknown_event_type` with the accepted codes in `known_types`
`vertical`	yes	A vertical active in wede, such as `healthcare`, `banking` or `logistics`. Otherwise `422 unknown_vertical`
`priority`	yes	`low`, `normal`, `high` or `critical`
`idempotency_key`	yes	1 to 128 characters, unique per operation. Sending it again returns `409 duplicate_event`, so retries are safe
`payload`	yes	Your operation data, as a JSON object
`metadata`	no	`zone_id`, `operator_id`, `sdk_version`, `offline_generated_at`, `connectivity_state_at_generation`
`destination`	no	A one-off recipient for this delivery: `phone`, `email` or `device_id`. Used only for this delivery and never kept with the event

Read your event types with GET /v1/catalog (see Event types). The API accepts the event and answers 202:

{
  "event_id": "fbea1e0d-8f6b-42f5-bf9b-58fe77430f53",
  "idempotency_key": "qs-0001",
  "status": "pending",
  "environment": "sandbox",
  "channel_selected": "rest_full",
  "request_id": "req-..."
}

channel_selected is how the event reached wede. The channel wede used to deliver it is channel_used on the event, and channel in the event.delivered webhook.

3. Read it back

curl https://api.wede.pt/v1/events/fbea1e0d-8f6b-42f5-bf9b-58fe77430f53 \
  -H "x-wede-api-key: $WEDE_API_KEY"

The response contains the event, with its status (pending, completed or failed), category, channel_used and environment, and a lifecycle array with one entry per step (status, channel, note, timestamp). In the sandbox, lifecycle notes start with sandbox:. The status is the delivery status: a sandbox event delivered online ends completed, and its stored payload is cleared, exactly as in production. pending means the event is queued (queued_offline) or not delivered yet. To list events, call GET /v1/events. It accepts status, type, category, vertical, zone_id, limit (default 50, maximum 200) and cursor. Pass the next_cursor of one page as cursor to get the next one. A key reads only the events of its own environment.

4. Receive signed webhooks

Create a webhook with an https URL (400 invalid_payload otherwise) and a secret of at least 16 characters. wede signs every delivery with it.

curl -X POST https://api.wede.pt/v1/webhooks \
  -H "x-wede-api-key: $WEDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.example.com/wede/webhooks",
    "events": ["event.created", "event.delivered", "event.failed", "sync.completed"],
    "secret": "'"$WEDE_WEBHOOK_SECRET"'"
  }'

Every delivery is a POST with this body:

{
  "id": "delivery-uuid",
  "event": "event.delivered",
  "created_at": "2026-09-26T10:15:02.114Z",
  "tenant_id": "tenant-uuid",
  "environment": "sandbox",
  "data": { "event_id": "...", "status": "completed", "channel": "rest_full", "attempts": 1 }
}

and these headers: X-Wede-Signature: t=<unix seconds>,v1=<hex>, X-Wede-Timestamp, X-Wede-Event, X-Wede-Delivery and X-Wede-Attempt. The v1 value is the HMAC-SHA256, with your secret, of the timestamp, a full stop and the raw request body. Verify it before you trust the content:

import crypto from 'node:crypto'
import express from 'express'

const app = express()

app.post('/wede/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Wede-Signature') ?? ''
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  const rawBody = req.body.toString('utf8')

  const expected = crypto
    .createHmac('sha256', process.env.WEDE_WEBHOOK_SECRET)
    .update(`${t}.${rawBody}`)
    .digest('hex')

  const valid =
    typeof parts.v1 === 'string' &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1, 'hex'), Buffer.from(expected, 'hex'))

  // Reject old timestamps to block replays (five minutes here)
  if (!valid || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(401)

  const delivery = JSON.parse(rawBody)
  // Use delivery.id to ignore a delivery you already processed
  res.sendStatus(200)
})

Answer with any 2xx status within 10 seconds. wede makes up to 3 attempts per delivery and disables a webhook after 10 consecutive failed attempts. To check your endpoint, send a real signed webhook.test delivery:

curl -X POST https://api.wede.pt/v1/webhooks/WEBHOOK_ID/test \
  -H "x-wede-api-key: $WEDE_API_KEY"

The response tells you whether your endpoint accepted it: { webhook_id, delivery_id, success, response_status, response_time_ms, error }.

5. Capture offline and sync

When a device or site has no connectivity, capture each operation at the moment it happens, keep it in local storage unchanged, and send the queue when the network returns. Each captured operation carries its idempotency_key, the capture time offline_generated_at and an integrity_hash: the SHA-256 of JSON.stringify(payload) + idempotency_key + offline_generated_at. See Sync. The wede SDKs do all of this automatically on the device. See SDKs. When connectivity returns, send the queue, up to 500 events per call:

curl -X POST https://api.wede.pt/v1/sync/batch \
  -H "x-wede-api-key: $WEDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "idempotency_key": "parcel-PX-2231-delivered",
      "type": "STATUS_UPDATE",
      "vertical": "logistics",
      "priority": "normal",
      "payload": { "parcel": "PX-2231", "status": "delivered" },
      "offline_generated_at": "2026-10-07T09:12:44.120Z",
      "integrity_hash": "<64 lowercase hex characters>"
    }]
  }'

The response has a summary (total, accepted, duplicates, rejected) and results, one entry per event. Each event in a batch is checked on its own:

accepted: stored and delivered exactly like an online event. You receive event.created with "origin": "sync", then the delivery webhooks.
duplicate: the operation already reached wede, online or in an earlier batch. It is never stored twice.
rejected: error_code says why: integrity_check_failed (the content changed after capture), unknown_vertical, unknown_event_type or persistence_error. The rest of the batch is still processed.

After each batch, wede sends a sync.completed webhook with the summary. On a mobile device the same flow runs with a session token instead of an API key. See Authentication.

6. Test connectivity loss in the sandbox

With a sandbox key, simulate a zone losing connectivity and watch the channel decision on new events:

curl -X POST https://api.wede.pt/v1/sandbox/simulate-connectivity \
  -H "x-wede-api-key: $WEDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "zone_id": "LIS-01", "connectivity_state": "sms_only", "duration_seconds": 300 }'

zone_id is the code of one of your zones (422 invalid_reference otherwise). connectivity_state is online, degraded, sms_only, voice_only or offline, and duration_seconds goes from 5 to 3600 (default 60). The simulation changes only the sandbox state of that zone, never the real one. Sandbox delivery uses the same channel decision as production: your continuity mode, the zone state and your channel order.

7. Go live

Replace the sandbox key with your production key:

export WEDE_API_KEY=wede_live_...

Nothing else changes. Production events are delivered through real channels and count toward usage. Sandbox and production are fully separate: the same idempotency_key can exist once in each, and each key sees only its own environment.

Optional: teams, dispatch and missions

Everything above (events, delivery through your channel cascade, offline capture and sync, webhooks) is the core that every integration uses. Operational verticals that send people to the field, such as emergency services, healthcare field teams, field services and delivery, can add the teams, dispatch and missions module on top of it. These operations are not available to an API key: they return 403 forbidden. They need a user session token with the right role. Dispatch needs company_admin, operational_supervisor or corporate_client; managing teams needs company_admin or company_tech. See Authentication and the API reference. A company_admin or company_tech can turn on automatic dispatch with PATCH /v1/tenant/dispatch-settings. With it on, a dispatch request for an action of your catalog (POST /v1/teams/dispatch/action) assigns the best-ranked team when it reaches your threshold, and otherwise returns requires_manual: true. Events still waiting for a team are listed with GET /v1/events?undispatched=true.

Next steps

Authentication

Keys, sessions, rotation and roles

SDKs

Five platforms, available under agreement

Sync

How offline operations are synchronised

API reference

Every endpoint in detail

Introduction

Core Concepts

Examples by Vertical

1. Get your API keys

2. Send your first event

3. Read it back

4. Receive signed webhooks

5. Capture offline and sync

6. Test connectivity loss in the sandbox

7. Go live

Optional: teams, dispatch and missions

Next steps

Authentication

SDKs

Sync

API reference

​1. Get your API keys

​2. Send your first event

​3. Read it back

​4. Receive signed webhooks

​5. Capture offline and sync

​6. Test connectivity loss in the sandbox

​7. Go live

​Optional: teams, dispatch and missions

​Next steps

Authentication

SDKs

Sync

API reference

1. Get your API keys

2. Send your first event

3. Read it back

4. Receive signed webhooks

5. Capture offline and sync

6. Test connectivity loss in the sandbox

7. Go live

Optional: teams, dispatch and missions

Next steps