Skip to content
Cynox IoT Documentation

Webhook format

Webhooks will always be delivered using an HTTP POST request to the URL you have specified. They will contain a request body in JSON format as well as several headers.

Basic webhook structure
{
  "eventId": "V2ViaG9va0V2ZW50OjQwNTc1ZGExLWVkM2MtNDExMS1hNDY1LTljMWVmZmY4NDU0MA==",
  "eventTimestamp": "2024-12-16T10:04:22.339404Z",
  "data": {
    "type": "..."
  }
}
  • The eventId provides a way to uniquely identify the event that triggered the webhook. It is recommended to ignore duplicate deliveries for the same event based on this property.
  • The eventTimestamp property provides the timestamp at which the event was triggered. This may be a while ago, in case the webhook took several attempts to be delivered.
  • data provides a tagged union based on the type property. This provides the actual event data.

Headers

Several HTTP headers are sent with every webhook:

  • X-Cynox-Webhook-ID: The ID of the webhook configuration that triggered this delivery
  • X-Cynox-Webhook-Subscription-ID: The ID of the subscription within the webhook configuration that triggered this delivery
  • X-Cynox-Webhook-Attempt: An integer denoting the attempt of this delivery. The first attempt will be 1, the 2nd will be 2, etc.
  • X-Cynox-Webhook-Timestamp: The timestamp of the delivery in ISO-8601 format. This is unrelated to the actual event timestamp, but instead denotes the time at which the server made the request.
  • X-Cynox-Webhook-HMAC: An HMAC of the request timestamp and body. This can be used to verify the authenticity of the message. See the section on security for more information.
Example set of headers
X-Cynox-Webhook-Id: V2ViaG9vazpiNTQzYzM2ZS0yNGYxLTRhODMtYjRiNi1jMjYwNmI4MmE2ODg=
X-Cynox-Webhook-Subscription-Id: V2ViaG9va1N1YnNjcmlwdGlvbjowZjc3NTZiNC1mNGE5LTQwYzEtOTVhNS03YzEyNTAxYjA0MzY=
X-Cynox-Webhook-Attempt: 1
X-Cynox-Webhook-Timestamp: 2024-12-16T13:20:55.074159+00:00
X-Cynox-Webhook-Hmac: 891767563f217c3a86bde2f03d2692e5ea3281d1efb300e5be33227f1c3bc224

Event format

The event data will use IDs and type names compatible with the GraphQL API. For example, when specifying a type of device, the GraphQL type name such as SocketMaster will be used; when specifying the type of command the GraphQL type name such as SocketMasterSetSwitchStateCommand will be used. The IDs for devices, commands and events will also be compatible with the GraphQL API and can be used directly to interact with it.

Device command created

Receive a webhook when a matching device command is first created.

{
  "data": {
    "type": "NewDeviceCommandEvent",
    "deviceId": "U29ja2V0TWFzdGVyOjhmMDc5MjNiLTU2N2ItNDczMy05ZDViLTcwMjI1Y2I2YTM0Zg==",
    "commandId": "U29ja2V0TWFzdGVyU2V0U3dpdGNoU3RhdGVDb21tYW5kOjhlMTRjNTBlLWVjMzYtNDAwYS1iZDkyLWMwYTU4MDNiNDBiYQ==",
    "deviceType": "SocketMaster",
    "commandType": "SocketMasterSetSwitchStateCommand"
  },
  "eventId": "V2ViaG9va0V2ZW50OjQwNTc1ZGExLWVkM2MtNDExMS1hNDY1LTljMWVmZmY4NDU0MA==",
  "eventTimestamp": "2024-12-16T10:04:22.339404Z"
}

Device command updated

Receive a webhook when a matching device command changes its execution state.

{
  "data": {
    "type": "DeviceCommandChangeEvent",
    "deviceId": "U29ja2V0TWFzdGVyOjhmMDc5MjNiLTU2N2ItNDczMy05ZDViLTcwMjI1Y2I2YTM0Zg==",
    "commandId": "U29ja2V0TWFzdGVyU2V0U3dpdGNoU3RhdGVDb21tYW5kOmRjZWIyOTNlLWUzNmQtNDA0NS1iMTBhLWQxMjJhMGQ2M2ZiZQ==",
    "deviceType": "SocketMaster",
    "commandType": "SocketMasterSetSwitchStateCommand",
    "executionState": "DONE"
  },
  "eventId": "V2ViaG9va0V2ZW50OmY5ZmQ4MTkzLWVkYzYtNDRmMS05MGYwLTI0MDI3YTc5ZDUyNg==",
  "eventTimestamp": "2024-12-16T11:51:40.691044Z"
}

Device status changed

Receive a webhook when a device’s status (Offline, Available, etc.) changes.

{
  "data": {
    "type": "DeviceStatusChangeEvent",
    "status": "AVAILABLE",
    "deviceId": "U29ja2V0TWFzdGVyOjhmMDc5MjNiLTU2N2ItNDczMy05ZDViLTcwMjI1Y2I2YTM0Zg==",
    "deviceType": "SocketMaster"
  },
  "eventId": "V2ViaG9va0V2ZW50OjE4MWQ4N2MxLThhYzMtNGM5ZS04NDZkLWZjODJjMDQzZGMwOA==",
  "eventTimestamp": "2024-12-16T11:43:08.492087Z"
}

JSON Schema

A JSON schema for the webhook data is available at https://api.staging.iot.cynox.de/schema/webhook/.