Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Lifecycle events

Amazon IoT can publish lifecycle events on the MQTT topics. These events are available by default and they can't be disabled.

Connect/Disconnect events

Amazon IoT publishes a message to the following MQTT topics when a client connects or disconnects:

The following is a list of JSON elements that are contained in the connection/disconnection messages published to the $aws/events/presence/connected/clientId topic.

A connect message has the following structure.

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1573002230757,
    "eventType": "connected",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "ipAddress": "192.0.2.0",
    "versionNumber": 0
}

A disconnect message has the following structure.

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1573002340451,
    "eventType": "disconnected",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "clientInitiatedDisconnect": true,
    "disconnectReason": "CLIENT_INITIATED_DISCONNECT",
    "versionNumber": 0
}

Handling client disconnections

The best practice is to always have a wait state implemented for lifecycle events, including Last Will and Testament (LWT) messages. When a disconnect message is received, your code should wait a period of time and verify a device is still offline before taking action. One way to do this is by using SQS Delay Queues. When a client receives a LWT or a lifecycle event, you can enqueue a message (for example, for 5 seconds). When that message becomes available and is processed (by Lambda or another service), you can first check if the device is still offline before taking further action.

Connect attempt failure event

Amazon IoT publishes a message to the following MQTT topic when a client is not authorized to connect or when a last will and testament is configured and the client is not authorized to publish to that last will topic.

$aws/events/presence/connect_failed/clientId

The following is a list of JSON elements that are contained in the connect authorization messages published to the $aws/events/presence/connect_failed/clientId topic.

A connection failure message has the following structure.

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1460065214626,
    "eventType": "connect_failed",
    "connectFailureReason": "AUTHORIZATION_FAILED",
    "principalIdentifier": "12345678901234567890123456789012",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "ipAddress" : "192.0.2.0"
}

Subscribe/Unsubscribe events

Amazon IoT publishes a message to the following MQTT topic when a client subscribes or unsubscribes to an MQTT topic:

$aws/events/subscriptions/subscribed/clientId

or

$aws/events/subscriptions/unsubscribed/clientId

Where clientId is the MQTT client ID that connects to the Amazon IoT message broker.

The message published to this topic has the following structure:

{
    "clientId": "186b5",
    "thingName": "exampleThing",
    "timestamp": 1460065214626,
    "eventType": "subscribed" | "unsubscribed",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "12345678901234567890123456789012",
    "topics" : ["foo/bar","device/data","dog/cat"]
}

The following is a list of JSON elements that are contained in the subscribed and unsubscribed messages published to the $aws/events/subscriptions/subscribed/clientId and $aws/events/subscriptions/unsubscribed/clientId topics.