# Event messages This section contains information about messages published by AWS IoT when things or jobs are updated or changed. For information about the AWS IoT Events service that allows you to create detectors to monitor your devices for failures or changes in operation, and to trigger actions when they occur, see [AWS IoT Events](https://aws.amazon.com/iot-events). ## How event messages are generated AWS IoT publishes event messages when certain events occur. For example, events are generated by the registry when things are added, updated, or deleted. Each event causes a single event message to be sent. Event messages are published over MQTT with a JSON payload. The content of the payload depends on the type of event. **Note** Event messages are guaranteed to be published once. It is possible for them to be published more than once. The ordering of event messages is not guaranteed. ### Policy for receiving event messages To receive event messages, your device must use an appropriate policy that allows it to connect to the AWS IoT device gateway and subscribe to MQTT event topics. You must also subscribe to the appropriate topic filters. The following is an example of the policy required for receiving lifecycle events: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:/$aws/events/*" ] } ] } ``` ## Enable events for AWS IoT Before subscribers to the reserved topics can receive messages, you must enable event messages from the AWS Management Console or by using the API or CLI. For information about the event messages that the different options manage, see the [Table of AWS IoT event configuration settings](#iot-events-settings-table). + To enable event messages, go to the [Settings](https://console.aws.amazon.com//iot/home#/settings) tab of the AWS IoT console and then, in the **Event-based messages** section, choose **Manage events**. You can specify the events that you want to manage. + To control which event types are published by using the API or CLI, call the [UpdateEventConfigurations](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateEventConfigurations.html) API or use the **update-event-configurations** CLI command. For example: ``` aws iot update-event-configurations --event-configurations "{\"THING\":{\"Enabled\": true}}" ``` **Note** All quotation marks (") are escaped with a backslash (\$1). You can get the current event configuration by calling the [DescribeEventConfigurations](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeEventConfigurations.html) API or by using the **describe-event-configurations** CLI command. For example:. ``` aws iot describe-event-configurations ``` **Table of AWS IoT event configuration settings** | Event category (AWS IoT Console: Settings: Event-based messages) | `eventConfigurations` key value (AWS CLI/API) | Event message topic | | --- | --- | --- | | *(Can only be configured by using the AWS CLI/API)* | `CA_CERTIFICATE` | `$aws/events/certificates/registered/caCertificateId` | | *(Can only be configured by using the AWS CLI/API)* | `CERTIFICATE` | `$aws/events/presence/connected/clientId` | | *(Can only be configured by using the AWS CLI/API)* | `CERTIFICATE` | `$aws/events/presence/disconnected/clientId` | | *(Can only be configured by using the AWS CLI/API)* | `CERTIFICATE` | `$aws/events/subscriptions/subscribed/clientId` | | *(Can only be configured by using the AWS CLI/API)* | `CERTIFICATE` | `$aws/events/subscriptions/unsubscribed/clientId` | | Job completed, canceled | `JOB` | `$aws/events/job/jobID/canceled` | | Job completed, canceled | `JOB` | `$aws/events/job/jobID/cancellation_in_progress` | | Job completed, canceled | `JOB` | `$aws/events/job/jobID/completed` | | Job completed, canceled | `JOB` | `$aws/events/job/jobID/deleted` | | Job completed, canceled | `JOB` | `$aws/events/job/jobID/deletion_in_progress` | | Job execution: success, failed, rejected, canceled, removed | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/canceled` | | Job execution: success, failed, rejected, canceled, removed | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/deleted` | | Job execution: success, failed, rejected, canceled, removed | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/failed` | | Job execution: success, failed, rejected, canceled, removed | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/rejected` | | Job execution: success, failed, rejected, canceled, removed | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/removed` | | Job execution: success, failed, rejected, canceled, removed | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/succeeded` | | Job execution: success, failed, rejected, canceled, removed | `JOB_EXECUTION` | `$aws/events/jobExecution/jobID/timed_out` | | Thing: created, updated, deleted | `THING` | `$aws/events/thing/thingName/created` | | Thing: created, updated, deleted | `THING` | `$aws/events/thing/thingName/updated` | | Thing: created, updated, deleted | `THING` | `$aws/events/thing/thingName/deleted` | | Thing group: added, removed | `THING_GROUP` | `$aws/events/thingGroup/thingGroupName/created` | | Thing group: added, removed | `THING_GROUP` | `$aws/events/thingGroup/thingGroupName/updated` | | Thing group: added, removed | `THING_GROUP` | `$aws/events/thingGroup/thingGroupName/deleted` | | Thing group hierarchy: added, removed | `THING_GROUP_HIERARCHY` | `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/added` | | Thing group hierarchy: added, removed | `THING_GROUP_HIERARCHY` | `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/removed` | | Thing group membership: added, removed | `THING_GROUP_MEMBERSHIP` | `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/added` | | Thing group membership: added, removed | `THING_GROUP_MEMBERSHIP` | `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/removed` | | Thing type: created, updated, deleted | `THING_TYPE` | `$aws/events/thingType/thingTypeName/created` | | Thing type: created, updated, deleted | `THING_TYPE` | `$aws/events/thingType/thingTypeName/updated` | | Thing type: created, updated, deleted | `THING_TYPE` | `$aws/events/thingType/thingTypeName/deleted` | | Thing type association: added, removed | `THING_TYPE_ASSOCIATION` | `$aws/events/thingTypeAssociation/thing/thingName/thingType/thingTypeName/added` `$aws/events/thingTypeAssociation/thing/thingName/thingType/thingTypeName/removed` | # Registry events The registry can publish event messages when things, thing types, and thing groups are created, updated, or deleted. These events, however, are not available by default. For information about how to turn on these events, see [Enable events for AWS IoT](iot-events.md#iot-events-enable). **Topics** + [ ## Thing events ](#registry-events-thing) + [ ## Thing type events ](#registry-events-thingtype) + [ ## Thing group events ](#registry-events-thinggroup) ## Thing events **Thing Created/Updated/Deleted** The registry publishes the following event messages when things are created, updated, or deleted: + `$aws/events/thing/thingName/created` + `$aws/events/thing/thingName/updated` + `$aws/events/thing/thingName/deleted` The messages contain the following example payload: ``` { "eventType" : "THING_EVENT", "eventId" : "f5ae9b94-8b8e-4d8e-8c8f-b3266dd89853", "timestamp" : 1234567890123, "operation" : "CREATED|UPDATED|DELETED", "accountId" : "123456789012", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "thingName" : "MyThing", "versionNumber" : 1, "thingTypeName" : null, "attributes": { "attribute3": "value3", "attribute1": "value1", "attribute2": "value2" } } ``` The payloads contain the following attributes: eventType Set to "THING\$1EVENT". eventId A unique event ID (string). timestamp The UNIX timestamp of when the event occurred. operation The operation that triggered the event. Valid values are: + CREATED + UPDATED + DELETED accountId Your AWS account ID. thingId The ID of the thing being created, updated, or deleted. thingName The name of the thing being created, updated, or deleted. versionNumber The version of the thing being created, updated, or deleted. This value is set to 1 when a thing is created. It is incremented by 1 each time the thing is updated. thingTypeName The thing type associated with the thing, if one exists. Otherwise, `null`. attributes A collection of name-value pairs associated with the thing. ## Thing type events **Topics** + [ ### Thing Type Created/Updated/Deprecated/Undeprecated/Deleted ](#registry-events-thingtype-crud) + [ ### Thing Type Associated or Disassociated with a Thing ](#registry-events-thingtype-assoc) ### Thing Type Created/Updated/Deprecated/Undeprecated/Deleted The registry publishes the following event messages when thing types are created, updated, deprecated, undeprecated, or deleted: + `$aws/events/thingType/thingTypeName/created` + `$aws/events/thingType/thingTypeName/updated` + `$aws/events/thingType/thingTypeName/deleted` The message contains the following example payload: ``` { "eventType" : "THING_TYPE_EVENT", "eventId" : "8827376c-4b05-49a3-9b3b-733729df7ed5", "timestamp" : 1234567890123, "operation" : "CREATED|UPDATED|DELETED", "accountId" : "123456789012", "thingTypeId" : "c530ae83-32aa-4592-94d3-da29879d1aac", "thingTypeName" : "MyThingType", "isDeprecated" : false|true, "deprecationDate" : null, "searchableAttributes" : [ "attribute1", "attribute2", "attribute3" ], "propagatingAttributes": [ { "userPropertyKey": "key", "thingAttribute": "model" }, { "userPropertyKey": "key", "connectionAttribute": "iot:ClientId" } ], "description" : "My thing type" } ``` The payloads contain the following attributes: eventType Set to "THING\$1TYPE\$1EVENT". eventId A unique event ID (string). timestamp The UNIX timestamp of when the event occurred. operation The operation that triggered the event. Valid values are: + CREATED + UPDATED + DELETED accountId Your AWS account ID. thingTypeId The ID of the thing type being created, updated, deprecated, or deleted. thingTypeName The name of the thing type being created, updated, deprecated, or deleted. isDeprecated `true` if the thing type is deprecated. Otherwise, `false`. deprecationDate The UNIX timestamp for when the thing type was deprecated. searchableAttributes A collection of name-value pairs associated with the thing type that can be used for searching. propagatingAttributes A list of propagating attributes. A propagating attribute can contain a thing attribute, a connection attribute, and a user property key. For more information, see [Adding propagating attributes for message enrichment](https://docs.aws.amazon.com//iot/latest/developerguide/thing-types-propagating-attributes.html). description A description of the thing type. ### Thing Type Associated or Disassociated with a Thing The registry publishes the following event messages when a thing type is associated or disassociated with a thing. + `$aws/events/thingTypeAssociation/thing/thingName/thingType/typeName/added` + `$aws/events/thingTypeAssociation/thing/thingName/thingType/typeName/removed` The following is an example of an `added` payload. Payloads for `removed` messages are similar. ``` { "eventId" : "87f8e095-531c-47b3-aab5-5171364d138d", "eventType" : "THING_TYPE_ASSOCIATION_EVENT", "operation" : "ADDED", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "thingName": "myThing", "thingTypeName" : "MyThingType", "timestamp" : 1234567890123, } ``` The payloads contain the following attributes: eventId A unique event ID (string). eventType Set to "THING\$1TYPE\$1ASSOCIATION\$1EVENT". operation The operation that triggered the event. Valid values are: + ADDED + REMOVED thingId The ID of the thing whose type association was changed. thingName The name of the thing whose type association was changed. thingTypeName The thing type associated with, or no longer associated with, the thing. timestamp The UNIX timestamp of when the event occurred. ## Thing group events **Topics** + [ ### Thing Group Created/Updated/Deleted ](#registry-events-thinggroup-crud) + [ ### Thing Added to or Removed from a Thing Group ](#registry-events-thinggroup-addremove) + [ ### Thing Group Added to or Deleted from a Thing Group ](#registry-events-thinggroup-adddelete) ### Thing Group Created/Updated/Deleted The registry publishes the following event messages when a thing group is created, updated, or deleted. + `$aws/events/thingGroup/groupName/created` + `$aws/events/thingGroup/groupName/updated` + `$aws/events/thingGroup/groupName/deleted` The following is an example of an `updated` payload. Payloads for `created` and `deleted` messages are similar. ``` { "eventType": "THING_GROUP_EVENT", "eventId": "8b9ea8626aeaa1e42100f3f32b975899", "timestamp": 1603995417409, "operation": "UPDATED", "accountId": "571EXAMPLE833", "thingGroupId": "8757eec8-bb37-4cca-a6fa-403b003d139f", "thingGroupName": "Tg_level5", "versionNumber": 3, "parentGroupName": "Tg_level4", "parentGroupId": "5fce366a-7875-4c0e-870b-79d8d1dce119", "description": "New description for Tg_level5", "rootToParentThingGroups": [ { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/TgTopLevel", "groupId": "36aa0482-f80d-4e13-9bff-1c0a75c055f6" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level1", "groupId": "bc1643e1-5a85-4eac-b45a-92509cbe2a77" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level2", "groupId": "0476f3d2-9beb-48bb-ae2c-ea8bd6458158" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level3", "groupId": "1d9d4ffe-a6b0-48d6-9de6-2e54d1eae78f" }, { "groupArn": "arn:aws:iot:us-west-2:571EXAMPLE833:thinggroup/Tg_level4", "groupId": "5fce366a-7875-4c0e-870b-79d8d1dce119" } ], "attributes": { "attribute1": "value1", "attribute3": "value3", "attribute2": "value2" }, "dynamicGroupMappingId": null } ``` The payloads contain the following attributes: eventType Set to "THING\$1GROUP\$1EVENT". eventId A unique event ID (string). timestamp The UNIX timestamp of when the event occurred. operation The operation that triggered the event. Valid values are: + CREATED + UPDATED + DELETED accountId Your AWS account ID. thingGroupId The ID of the thing group being created, updated, or deleted. thingGroupName The name of the thing group being created, updated, or deleted. versionNumber The version of the thing group. This value is set to 1 when a thing group is created. It is incremented by 1 each time the thing group is updated. parentGroupName The name of the parent thing group, if one exists. parentGroupId The ID of the parent thing group, if one exists. description A description of the thing group. rootToParentThingGroups An array of information about the parent thing group. There is one element for each parent thing group, starting from the root thing group and continuing to the thing group's parent. Each entry contains the thing group's `groupArn` and `groupId`. attributes A collection of name-value pairs associated with the thing group. ### Thing Added to or Removed from a Thing Group The registry publishes the following event messages when a thing is added to or removed from a thing group. + `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/added` + `$aws/events/thingGroupMembership/thingGroup/thingGroupName/thing/thingName/removed` The messages contain the following example payload: ``` { "eventType" : "THING_GROUP_MEMBERSHIP_EVENT", "eventId" : "d684bd5f-6f6e-48e1-950c-766ac7f02fd1", "timestamp" : 1234567890123, "operation" : "ADDED|REMOVED", "accountId" : "123456789012", "groupArn" : "arn:aws:iot:ap-northeast-2:123456789012:thinggroup/MyChildThingGroup", "groupId" : "06838589-373f-4312-b1f2-53f2192291c4", "thingArn" : "arn:aws:iot:ap-northeast-2:123456789012:thing/MyThing", "thingId" : "b604f69c-aa9a-4d4a-829e-c480e958a0b5", "membershipId" : "8505ebf8-4d32-4286-80e9-c23a4a16bbd8" } ``` The payloads contain the following attributes: eventType Set to "THING\$1GROUP\$1MEMBERSHIP\$1EVENT". eventId The event ID. timestamp The UNIX timestamp for when the event occurred. operation `ADDED` when a thing is added to a thing group. `REMOVED` when a thing is removed from a thing group. accountId Your AWS account ID. groupArn The ARN of the thing group. groupId The ID of the group. thingArn The ARN of the thing that was added or removed from the thing group. thingId The ID of the thing that was added or removed from the thing group. membershipId An ID that represents the relationship between the thing and the thing group. This value is generated when you add a thing to a thing group. ### Thing Group Added to or Deleted from a Thing Group The registry publishes the following event messages when a thing group is added to or removed from another thing group. + `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/added` + `$aws/events/thingGroupHierarchy/thingGroup/parentThingGroupName/childThingGroup/childThingGroupName/removed` The message contains the following example payload: ``` { "eventType" : "THING_GROUP_HIERARCHY_EVENT", "eventId" : "264192c7-b573-46ef-ab7b-489fcd47da41", "timestamp" : 1234567890123, "operation" : "ADDED|REMOVED", "accountId" : "123456789012", "thingGroupId" : "8f82a106-6b1d-4331-8984-a84db5f6f8cb", "thingGroupName" : "MyRootThingGroup", "childGroupId" : "06838589-373f-4312-b1f2-53f2192291c4", "childGroupName" : "MyChildThingGroup" } ``` The payloads contain the following attributes: eventType Set to "THING\$1GROUP\$1HIERARCHY\$1EVENT". eventId The event ID. timestamp The UNIX timestamp for when the event occurred. operation `ADDED` when a thing is added to a thing group. `REMOVED` when a thing is removed from a thing group. accountId Your AWS account ID. thingGroupId The ID of the parent thing group. thingGroupName The name of the parent thing group. childGroupId The ID of the child thing group. childGroupName The name of the child thing group. # Jobs events The AWS IoT Jobs service publishes to reserved topics on the MQTT protocol when jobs are pending, completed, or canceled, and when a device reports success or failure when running a job. Devices or management and monitoring applications can track the status of jobs by subscribing to these topics. **How to enable jobs events** Response messages from the AWS IoT Jobs service don't pass through the message broker and they can't be subscribed to by other clients or rules. To subscribe to job activity-related messages, use the `notify` and `notify-next` topics. For information about jobs topics, see [Job topics](reserved-topics.md#reserved-topics-job). To be notified of jobs updates, enable these jobs events by using the AWS Management Console, or by using the API or CLI. For more information, see [Enable events for AWS IoT](iot-events.md#iot-events-enable). **How jobs events work** Because it can take some time to cancel or delete a job, two messages are sent to indicate the start and end of a request. For example, when a cancellation request starts, a message is sent to the `$aws/events/job/jobID/cancellation_in_progress` topic. When the cancellation request is complete, a message is sent to the `$aws/events/job/jobID/canceled` topic. A similar process occurs for a job deletion request. Management and monitoring applications can subscribe to these topics to keep track of the status of jobs. For more information about publishing and subscribing to MQTT topics, see [Device communication protocols](protocols.md). **Job event types** The following examples show the different types of jobs events: **Job Completed/Canceled/Deleted** The AWS IoT Jobs service publishes a message on an MQTT topic when a job is completed, canceled, deleted, or when cancellation or deletion are in progress: + `$aws/events/job/jobID/completed` + `$aws/events/job/jobID/canceled` + `$aws/events/job/jobID/deleted` + `$aws/events/job/jobID/cancellation_in_progress` + `$aws/events/job/jobID/deletion_in_progress` The `completed` message contains the following example payload: ``` { "eventType": "JOB", "eventId": "7364ffd1-8b65-4824-85d5-6c14686c97c6", "timestamp": 1234567890, "operation": "completed", "jobId": "27450507-bf6f-4012-92af-bb8a1c8c4484", "status": "COMPLETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/a39f6f91-70cf-4bd2-a381-9c66df1a80d0", "arn:aws:iot:us-east-1:123456789012:thinggroup/2fc4c0a4-6e45-4525-a238-0fe8d3dd21bb" ], "description": "My Job Description", "completedAt": 1234567890123, "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 } } ``` The `canceled` message contains the following example payload. ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "canceled", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123 } ``` The `deleted` message contains the following example payload. ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deleted", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" } ``` The `cancellation_in_progress` message contains the following example payload: ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "cancellation_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELLATION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" } ``` The `deletion_in_progress` message contains the following example payload: ``` { "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deletion_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" } ``` **Job Execution Terminal Status** The AWS IoT Jobs service publishes a message when a device updates a job execution to terminal status: + `$aws/events/jobExecution/jobID/succeeded` + `$aws/events/jobExecution/jobID/failed` + `$aws/events/jobExecution/jobID/rejected` + `$aws/events/jobExecution/jobID/canceled` + `$aws/events/jobExecution/jobID/timed_out` + `$aws/events/jobExecution/jobID/removed` + `$aws/events/jobExecution/jobID/deleted` The message contains the following example payload: ``` { "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed|timed_out", "jobId": "154b39e5-60b0-48a4-9b73-f6f8dd032d27", "thingArn": "arn:aws:iot:us-east-1:123456789012:myThing/6d639fbc-8f85-4a90-924d-a2867f8366a7", "status": "SUCCEEDED|FAILED|REJECTED|CANCELED|REMOVED|TIMED_OUT", "statusDetails": { "key": "value" } } ``` # Command execution events AWS IoT publishes event messages to MQTT topics when command executions change status. You can use these events to monitor command execution progress and build applications that respond to status changes. **Command execution event topics** Command execution events are published to the following MQTT topic: ``` $aws/events/commandExecution/commandId/status ``` Where: + `commandId` is the identifier of the command. + `status` is the status of the command execution. Valid values are: `CREATED`, `IN_PROGRESS`, `SUCCEEDED`, `FAILED`, `REJECTED`, `TIMED_OUT`. To receive notifications for all commands and all statuses, subscribe to the following topic using wildcard characters: ``` $aws/events/commandExecution/+/# ``` **Command execution event message** When a command execution status changes, AWS IoT publishes an event message to the corresponding MQTT topic. The message contains the following example payload: ``` { "executionId": "2bd65c51-4cfd-49e4-9310-d5cbfdbc8554", "status": "FAILED", "statusReason": { "reasonCode": "DEVICE_TOO_BUSY", "reasonDescription": "" }, "eventType": "COMMAND_EXECUTION", "commandArn": "arn:aws:iot:us-east-1:123456789012:command/0b9d9ddf-e873-43a9-8e2c-9fe004a90086", "targetArn": "arn:aws:iot:us-east-1:123456789012:thing/5006c3fc-de96-4def-8427-7eee36c6f2bd", "timestamp": 1717708862107 } ``` The payload contains the following attributes: **executionId** A unique identifier for the command execution (string). **status** The status of the command execution. Valid values are: `CREATED`, `IN_PROGRESS`, `SUCCEEDED`, `FAILED`, `REJECTED`, `TIMED_OUT`. **statusReason** An object containing additional information about the status, if available. Contains `reasonCode` and `reasonDescription` fields. **eventType** Set to "COMMAND\$1EXECUTION". **commandArn** The Amazon Resource Name (ARN) of the command. **targetArn** The ARN of the target device (thing or client) for the command execution. **timestamp** The UNIX timestamp of when the event occurred. # Lifecycle events AWS IoT can publish lifecycle events on the MQTT topics. These events are available by default and they can't be disabled. **Note** Lifecycle messages might be sent out of order. You might receive duplicate messages. `thingName` will only be included if the client is connecting using the [exclusive thing](exclusive-thing.md) feature. **Topics** + [ ## Connect/Disconnect events ](#connect-disconnect) + [ ## Connect attempt failure event ](#connect-authfailure-event) + [ ## Subscribe/Unsubscribe events ](#subscribe-unsubscribe-events) ## Connect/Disconnect events **Note** With AWS IoT Device Management fleet indexing, you can search for things, run aggregate queries, and create dynamic groups based on thing Connect/Disconnect events. For more information, see [ Fleet indexing](https://docs.aws.amazon.com//iot/latest/developerguide/iot-indexing.html). AWS IoT publishes a message to the following MQTT topics when a client connects or disconnects: + `$aws/events/presence/connected/clientId` – A client connected to the message broker. + `$aws/events/presence/disconnected/clientId` – A client disconnected from the message broker. 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. **clientId** The client ID of the connecting or disconnecting client. Client IDs that contain \$1 or \$1 do not receive lifecycle events. **thingName** The name of your IoT thing. `thingName` will only be included if the client is connecting using the [exclusive thing](exclusive-thing.md) feature. **clientInitiatedDisconnect** True if the client initiated the disconnect. Otherwise, false. Found in disconnect messages only. **disconnectReason** The reason why the client is disconnecting. Found in disconnect messages only. The following table contains valid values and whether the broker will send [Last Will and Testament (LWT) messages](mqtt.md#mqtt-lwt) when the disconnection occurs. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/life-cycle-events.html) 1If the device has an active connection before receiving this error. 2To prevent Last Will and Testament (LWT) messages, set `preventWillMessage=true` to override the `DeleteConnection` API's default LWT sending behavior. **eventType** The type of event. Valid values are `connected` or `disconnected`. **ipAddress** The IP address of the connecting client. This can be in IPv4 or IPv6 format. Found in connection messages only. **principalIdentifier** The credential used to authenticate. For TLS mutual authentication certificates, this is the certificate ID. For other connections, this is IAM credentials. **sessionIdentifier** A globally unique identifier in AWS IoT that exists for the life of the session. **timestamp** An approximation of when the event occurred. **versionNumber** The version number for the lifecycle event. This is a monotonically increasing long integer value for each client ID connection. The version number can be used by a subscriber to infer the order of lifecycle events. The connect and disconnect messages for a client connection have the same version number. The version number might skip values and is not guaranteed to be consistently increasing by 1 for each event. If a client is not connected for approximately one hour, the version number is reset to 0. For persistent sessions, the version number is reset to 0 after a client has been disconnected longer than the configured time-to-live (TTL) for the persistent session. 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](mqtt.md). 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](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-delay-queues.html). 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 AWS 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. **clientId** The client ID of the client that attempted and failed to connect. Client IDs that contain \$1 or \$1 do not receive lifecycle events. **thingName** The name of your IoT thing. `thingName` will only be included if the client is connecting using the [exclusive thing](exclusive-thing.md) feature. **timestamp** An approximation of when the event occurred. **eventType** The type of event. Valid value is `connect_failed`. **connectFailureReason** The reason why the connection fails. Valid value is `AUTHORIZATION_FAILED`. **principalIdentifier** The credential used to authenticate. For TLS mutual authentication certificates, this is the certificate ID. For other connections, this is IAM credentials. **sessionIdentifier** A globally unique identifier in AWS IoT that exists for the life of the session. **ipAddress** The IP address of the connecting client. This can be in IPv4 or IPv6 format. Found in connection messages only. 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 AWS 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 AWS 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. clientId The client ID of the subscribing or unsubscribing client. Client IDs that contain \$1 or \$1 do not receive lifecycle events. thingName The name of your IoT thing. `thingName` will only be included if the client is connecting using the [exclusive thing](exclusive-thing.md) feature. eventType The type of event. Valid values are `subscribed` or `unsubscribed`. principalIdentifier The credential used to authenticate. For TLS mutual authentication certificates, this is the certificate ID. For other connections, this is IAM credentials. sessionIdentifier A globally unique identifier in AWS IoT that exists for the life of the session. timestamp An approximation of when the event occurred. topics An array of the MQTT topics to which the client has subscribed. **Note** Lifecycle messages might be sent out of order. You might receive duplicate messages.