Sync

What sync does

When a device or system works without connectivity, it captures each operation locally at the moment it happens. When connectivity returns, it sends them to wede in one batch. wede checks every event on its own, stores each operation once, and then delivers the accepted ones exactly as if they had been sent online.

How it works

Capture

Capture each operation when it happens, with its idempotency_key, the capture time (offline_generated_at) and an integrity checksum. The wede SDKs do this for you. Store the captured object unchanged.

Send the batch

When connectivity returns, send up to 500 captured events to POST /v1/sync/batch.

Read the results

wede returns one result per event: accepted, duplicate or rejected, with a reason for rejections.

Delivery

Accepted events follow the same delivery path as online events and trigger the same webhooks.

Capture and send

With the wede SDKs, capture and sync are automatic: operations are kept on the device and sent when the connection returns. See SDKs. Without an SDK, capture each operation yourself and send the batch:

// When the operation happens, even without connectivity
async function capture(event: { type: string; vertical: string; priority: string; idempotency_key: string; payload: Record<string, unknown> }) {
  const offline_generated_at = new Date().toISOString()
  const bytes = new TextEncoder().encode(JSON.stringify(event.payload) + event.idempotency_key + offline_generated_at)
  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))
  const integrity_hash = [...digest].map(b => b.toString(16).padStart(2, '0')).join('')
  return { ...event, offline_generated_at, integrity_hash }
}

const captured = await capture({
  type: 'delivery_confirmed',
  vertical: 'logistics',
  priority: 'normal',
  idempotency_key: 'parcel-PX-2231-delivered',
  payload: { parcel: 'PX-2231' },
})
// store `captured` locally, unchanged

// When connectivity returns
const res = await fetch('https://api.wede.pt/v1/sync/batch', {
  method: 'POST',
  headers: { 'x-wede-api-key': process.env.WEDE_API_KEY!, 'content-type': 'application/json' },
  body: JSON.stringify({ events: queuedEvents }),
})
const { summary, results } = await res.json()
// summary: { total, accepted, duplicates, rejected }; results: one entry per event

On a device or in a browser, use a session token instead of an API key. See Authentication.

Batch contract

POST /v1/sync/batch with { "events": [ ... ] }, from 1 to 500 events. A malformed batch returns 400 invalid_payload and nothing is stored.

Field	Required	Description
`idempotency_key`	Yes	1 to 128 characters, unique per operation
`type`	Yes	An active event type of your catalog for this vertical. See Events
`vertical`	Yes	A vertical active in wede
`priority`	Yes	`low`, `normal`, `high` or `critical`
`payload`	Yes	JSON object
`offline_generated_at`	Yes	ISO 8601 time of capture
`integrity_hash`	Yes	64 hexadecimal characters (see below)
`connectivity_state_at_generation`	No	`online`, `degraded`, `sms_only`, `voice_only` or `offline`
`metadata`	No	`zone_id` (the code of one of your zones) and `location` (`lat`, `lng`), as in `POST /v1/events`. Not part of the checksum

Integrity checksum

integrity_hash is the SHA-256, in lowercase hexadecimal, of this string:

JSON.stringify(payload) + idempotency_key + offline_generated_at

JSON.stringify(payload) is the compact JSON of the payload with its keys in the order you send them. Any change to the payload, the key or the capture time after capture makes the checksum fail.

Response

{
  "summary": { "total": 3, "accepted": 1, "duplicates": 1, "rejected": 1 },
  "results": [
    {
      "idempotency_key": "px-2231-delivered",
      "event_id": "5b7f6c1e-0a2d-4c8e-9f31-7d2a6b4e8c10",
      "result": "accepted",
      "error_code": null,
      "error_message": null
    },
    {
      "idempotency_key": "px-2230-delivered",
      "event_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f",
      "result": "duplicate",
      "error_code": null,
      "error_message": null
    },
    {
      "idempotency_key": "px-2229-delivered",
      "event_id": null,
      "result": "rejected",
      "error_code": "integrity_check_failed",
      "error_message": "..."
    }
  ]
}

The response is 200 whenever the batch is well formed, even if some events are rejected. Read results to know what happened to each event.

Duplicates

An operation that already reached wede, online through POST /v1/events or in an earlier batch, is returned as duplicate with the event_id of the existing event. It is never stored twice. duplicates is your proof against double counting.

Rejections

`error_code`	Meaning	What to do
`integrity_check_failed`	The checksum does not match the event	Do not resend as is: the content changed after capture
`unknown_vertical`	The vertical is not active in wede	Fix the vertical
`unknown_event_type`	The type is not in your catalog for this vertical and is not an active category	Create the type in your catalog, then resend
`persistence_error`	wede could not store the event	Resend the event in a later batch

A rejection affects only that event. The other events of the batch are still accepted.

Refused events are kept

wede keeps every event it refuses with its full content as it arrived, the device that sent it, its place in the device’s numbering and the reason, whether it came in a batch or by SMS, satellite or LoRa. Each refusal is a record that cannot be changed, so the trail of an operation never depends on the device keeping it. The result of a refused event says so with recorded: true. Your organisation sees them in the dashboard, on the Refused page, and reads them with GET /v1/sync/rejected. wede never sees their content. At the end of the retention period the content and the device are removed; the key, the reason, the device number and a checksum of the content stay. A device that kept refused events with an SDK version before 2.17.0 can hand them to wede only to be kept, never processed again, with POST /v1/sync/rejected. The same event sent twice is kept once.

Integrity incidents

A checksum that does not match is treated as a possible security incident. wede rejects that event only, records an incident that cannot be altered, and alerts your tenant administrators by email. With a sandbox key the event is refused and the incident is recorded the same way, marked as sandbox, but nobody is alerted: you are testing. To rehearse it end to end, use the Proof kit.

After sync

Each accepted event:

is stored with offline_generated_at and, when sent, connectivity_state_at_generation;
sends an event.created webhook with origin: "sync";
follows the same delivery path as an online event, with the same event.delivered, event.failed and event.status_changed webhooks;
becomes completed as soon as it is delivered, and its stored payload is cleared (for a type that sends a team, when the event is closed or its missions end). It stays pending only while it is queued for store-and-forward.

Once per batch, wede sends a sync.completed webhook with the summary. Events sent in a batch can carry metadata.zone_id and metadata.location, as online events do. They are not part of the checksum.

Sync status

GET /v1/sync/status summarises the events of your tenant that were captured offline:

{
  "tenant_id": "b2c4...",
  "synced_total": 1240,
  "pending": 12,
  "completed": 1220,
  "failed": 8,
  "last_sync_at": "2026-09-26T10:14:03.000Z"
}

An API key sees its own environment. A session sees production and can pass environment=sandbox.

Best practices

Create the idempotency_key when the operation happens, not when you send it.
Store captured events unchanged. Any change breaks the checksum.
Send batches as soon as connectivity returns, up to 500 events each.
Always read results. Resend only events rejected with persistence_error, or fixed after unknown_event_type or unknown_vertical.
A captured event can also be sent online with POST /v1/events. If the connection drops before you get the answer, keep it in the queue: the batch will return it as duplicate if it already arrived.

Introduction

Core Concepts

Examples by Vertical

What sync does

How it works

Capture and send

Batch contract

Integrity checksum

Response

Duplicates

Rejections

Refused events are kept

Integrity incidents

After sync

Sync status

Best practices

​What sync does

​How it works

​Capture and send

​Batch contract

​Integrity checksum

​Response

​Duplicates

​Rejections

​Refused events are kept

​Integrity incidents

​After sync

​Sync status

​Best practices

What sync does

How it works

Capture and send

Batch contract

Integrity checksum

Response

Duplicates

Rejections

Refused events are kept

Integrity incidents

After sync

Sync status

Best practices