Sync batch

POST /v1/sync/batch

Sends events that were captured while the device had no connectivity. wede checks each event on its own: a problem with one event never rejects the others. Accepted events follow exactly the same delivery path as events sent with POST /v1/events.

The wede SDKs capture events with the right checksum and send them for you. See SDKs. Without an SDK, compute the checksum as described below.

Authentication

API key or session token with the sync:write permission. API keys have it. Events are stored in the environment of the credential.

Request body

object[]

required

1 to 500 events.

Show properties

string

required

1 to 128 characters. Identifies the operation. Use the same key you would use online, so an operation that already reached wede is recognised as a duplicate.

string

required

Event type: an active type of your catalog for this vertical (see GET /v1/catalog).

string

required

A vertical active in wede.

string

Optional. low, normal, high or critical. Without it, the type’s default priority in your catalog applies (normal when the type has none). When your catalog marks the type’s priority as fixed, that priority always applies. Same rule as online: see Who decides the priority.

object

required

Your operation data, exactly as it was when captured.

string

required

ISO 8601 date-time of capture, for example 2026-09-26T08:41:17.000Z.

string

required

64 lowercase hex characters: SHA-256 of JSON.stringify(payload) + idempotency_key + offline_generated_at, computed at capture time.

string

Connectivity at capture time: online, degraded, sms_only, voice_only or offline.

object

Optional zone_id (the code of one of your zones), location (lat, lng) and device_id (the app installation that made the request, which receives the notices about it), as in POST /v1/events. Not part of the checksum.

object

Optional, outside the checksum: { "phone": "+351912345678", "shared": true }, the number the person chose to share in your app, with the same rules as in POST /v1/events. Kept only when your organisation turned on sms_requester_status, and removed when the request is completed or closed.

Integrity checksum

The checksum proves the event was not changed between capture and sync. Compute it once, when you capture the event, and store the event unchanged:

import { createHash } from 'node:crypto'

const payload = { parcel: 'PX-2231' }
const idempotencyKey = 'courier-17-2026-09-26-0008'
const offlineGeneratedAt = new Date().toISOString()

const integrityHash = createHash('sha256')
  .update(JSON.stringify(payload) + idempotencyKey + offlineGeneratedAt)
  .digest('hex')

import hashlib, json
from datetime import datetime, timezone

payload = {"parcel": "PX-2231"}
idempotency_key = "courier-17-2026-09-26-0008"
offline_generated_at = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")

serialised = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
integrity_hash = hashlib.sha256(
    (serialised + idempotency_key + offline_generated_at).encode("utf-8")
).hexdigest()

wede recomputes the checksum from the JSON it receives, with JSON.stringify semantics: no spaces, keys in the order you sent them. Any difference in serialisation (key order, spacing, number formatting, escaping) produces a different hash and the event is rejected with integrity_check_failed. This is why the SDKs are the safest way to capture events.

Example

curl -X POST https://api.wede.pt/v1/sync/batch \
  -H "x-wede-api-key: wede_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "idempotency_key": "courier-17-2026-09-26-0008",
        "type": "delivery_confirmed",
        "vertical": "logistics",
        "priority": "normal",
        "payload": { "parcel": "PX-2231" },
        "offline_generated_at": "2026-09-26T08:41:17.000Z",
        "connectivity_state_at_generation": "offline",
        "integrity_hash": "3f5c1e0b9a7d4c2e8f6a1b3d5e7f9a0c2e4b6d8f0a1c3e5b7d9f1a3c5e7b9d0f"
      }
    ]
  }'

Response

200 OK, even when some events are rejected. Check summary and each entry of results.

{
  "summary": { "total": 3, "accepted": 1, "duplicates": 1, "rejected": 1 },
  "results": [
    {
      "idempotency_key": "courier-17-2026-09-26-0008",
      "event_id": "7c2a4e1f-0b3d-4a5c-9e8f-1d2c3b4a5e6f",
      "result": "accepted",
      "error_code": null,
      "error_message": null
    },
    {
      "idempotency_key": "courier-17-2026-09-26-0007",
      "event_id": "1a9f3c5e-7b2d-4e6f-8a0c-2e4b6d8f0a1c",
      "result": "duplicate",
      "error_code": null,
      "error_message": null
    },
    {
      "idempotency_key": "courier-17-2026-09-26-0009",
      "event_id": null,
      "result": "rejected",
      "error_code": "integrity_check_failed",
      "error_message": "..."
    }
  ]
}

object

Show properties

integer

Events in the batch.

integer

New events stored.

integer

Events wede already had.

integer

Events not stored.

object[]

One entry per event, in the order you sent them.

Show properties

string

The event’s key.

string | null

ID of the stored event, for accepted and duplicate. null for rejected.

string

accepted, duplicate or rejected.

string | null

Reason for rejected, otherwise null.

string | null

Human-readable reason, otherwise null.

Results

`result`	What to do
`accepted`	Stored and sent for delivery. Remove it from your queue
`duplicate`	wede already had this operation, online or from an earlier batch. It is never stored twice. Remove it from your queue
`rejected`	Not stored. Fix the cause shown in `error_code`

`error_code`	Meaning
`integrity_check_failed`	The checksum does not match the event. The event was changed after capture or serialised differently
`unknown_vertical`	`vertical` is not registered or not active
`unknown_event_type`	`type` is neither an active type of your catalog for this vertical nor an active category
`persistence_error`	The event could not be stored. Send it again in a later batch

Every integrity_check_failed is recorded as a security incident and your tenant administrators are alerted. Only that event is rejected: the rest of the batch, the device and the session are unaffected.

After the batch

For each accepted event, wede emits event.created with "origin": "sync" and delivers the event exactly as it delivers online events: once delivered, the event is completed and its stored payload is cleared (kept until the event is closed when its type sends a team). When the batch is processed, wede emits sync.completed with the summary. See Webhook events.

Errors

Status	Code	When
400	`invalid_payload`	The body is not valid JSON, `events` is empty or has more than 500 items, or an event is missing a field or has an invalid one. `details` lists each problem. Nothing is stored
401	`unauthorized`	Credential missing, malformed, revoked or expired
403	`forbidden`	The credential lacks `sync:write`
503	`service_unavailable`	The API key could not be validated right now. Retry the batch

Overview

Authentication

Events

Teams & Dispatch

Missions

Zones

Billing

Tenant

Webhooks

Sync

Policies

Connectivity

Sandbox

Parsers

Onboarding

Authentication

Request body

Integrity checksum

Example

Response

Results

After the batch

Errors

​Authentication

​Request body

​Integrity checksum

​Example

​Response

​Results

​After the batch

​Errors

Authentication

Request body

Integrity checksum

Example

Response

Results

After the batch

Errors