Event messages - Amazon IoT Core
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).

Event messages

This section contains information about messages published by Amazon IoT when things or jobs are updated or changed. For information about the Amazon 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 Amazon IoT Events.

How event messages are generated

Amazon 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 Amazon 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:region:account:/$aws/events/*" ] }] }

Enable events for Amazon IoT

Before subscribers to the reserved topics can receive messages, you must enable event messages from the Amazon Web Services Management Console or by using the API or CLI. For information about the event messages that the different options manage, see the Table of Amazon IoT event configuration settings.

  • To enable event messages, go to the Settings tab of the Amazon 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 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 (\).

You can get the current event configuration by calling the DescribeEventConfigurations API or by using the describe-event-configurations CLI command. For example:.

aws iot describe-event-configurations

Table of Amazon IoT event configuration settings

Event category

(Amazon IoT Console: Settings: Event-based messages)

eventConfigurations key value

(Amazon CLI/API)

Event message topic

(Can only be configured by using the Amazon CLI/API)

CA_CERTIFICATE

$aws/events/certificates/registered/caCertificateId

(Can only be configured by using the Amazon CLI/API)

CERTIFICATE

$aws/events/presence/connected/clientId

(Can only be configured by using the Amazon CLI/API)

CERTIFICATE

$aws/events/presence/disconnected/clientId

(Can only be configured by using the Amazon CLI/API)

CERTIFICATE

$aws/events/subscriptions/subscribed/clientId

(Can only be configured by using the Amazon 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