Skip to content
IoT OS

Signed delivery of one integration event

POST

Sent to the application’s webhook endpoint (HTTPS on port 443, one per application, which must grant events:read and alerts:read) for each event on its granted devices, in journal order, one delivery at a time and at most one send per second per endpoint. The body is the same envelope the feed returns.

Signature. X-Iot-Signature is v1= followed by the hex HMAC-SHA256 of X-Iot-Timestamp + "." + X-Iot-Delivery-Id + "." + raw body, keyed with the endpoint’s signing secret. Verify it over the raw bytes before parsing, reject a timestamp more than 300 seconds from your clock, and deduplicate by event id before returning 2xx: a valid signature can be replayed.

Retries. A 2xx response confirms delivery. Timeouts (3 s to connect, 5 s to transfer), network errors, 408, 425, 429 and 5xx are retried after 10 s, 30 s, 2 min and 10 min, up to five attempts within 24 hours; any other status, including a redirect, fails the delivery at once. A delivery that is still being retried holds back newer ones for that endpoint. Saving the endpoint rotates the secret, cancels pending deliveries and starts at the current head of the journal; recover gaps through the feed. Revoking the application or changing its grants disables the endpoint.

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Iot-Delivery-Id
required
string format: uuid

The delivery’s UUID, the same on every attempt.

X-Iot-Timestamp
required
string
/^[0-9]+$/

Unix seconds when this attempt was signed.

X-Iot-Signature
required
string
/^v1=[a-f0-9]{64}$/

v1=<hex HMAC-SHA256>.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of: discriminator: type

An alert was activated, cleared or acknowledged; data is the alert snapshot.

object
id
required

Stable across feed reads, webhook retries and redelivery.

string format: uuid
schema_version
required
Allowed value: integration-event.v1
type
required
string
Allowed values: alert.activated.v1 alert.cleared.v1 alert.acknowledged.v1
occurred_at
required

When the source transition happened.

string format: date-time
recorded_at
required

When the event was written to the journal (not its commit time).

string format: date-time
data
required

A snapshot of one alert episode. The same object is the data of the alert.*.v1 events.

object
uuid
required
string format: uuid
episode
required
integer
>= 1
condition
required
string
Allowed values: active cleared
activated_at
required
string | null format: date-time
cleared_at
required
string | null format: date-time
acknowledged_at
required
string | null format: date-time
workflow_uuid
required
string format: uuid
workflow_name
required
string
device_uuid
required
string format: uuid
execution_stopped_reason
required

Why the alert’s workflow stopped evaluating, for example binding_changed.

string | null

Example 

{
  "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "schema_version": "integration-event.v1",
  "type": "geofence.exited.v1",
  "occurred_at": "2026-10-12T08:10:00+00:00",
  "recorded_at": "2026-10-12T08:10:01+00:00",
  "data": {
    "uuid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "geofence_uuid": "1e2d3c4b-5a69-4788-9a6b-5c4d3e2f1a0b",
    "geofence_name": "North paddock",
    "assignment_uuid": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
    "device_uuid": "3f8a1c2e-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
    "type": "exited",
    "source_event_uuid": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
    "occurred_at": "2026-10-12T08:09:58Z"
  }
}

Responses

Section titled “Responses”

2XX

Section titled “2XX”

Delivered. Return it only after recording the event id.

default

Section titled “default”

Not delivered. 408, 425, 429 and 5xx are retried; any other status fails the delivery.

Report a problem with this page