Event Schemas for Alexa Smart Properties

Alexa Smart Properties enables you to receive notifications about Alexa events. Events are published to Amazon Simple Notification Service (SNS).

For details about how to set up events, see Receive Events for Alexa Smart Properties Core.

Event types

The following table contains the Alexa Smart Properties events to which you can subscribe to receive notifications.

Event Name Description Schema

Alexa.Automation.Execution.Completion

An automation sequence execution is complete. Either all actions are invoked and completed successfully, or there were failures.

Automation execution completion event

Alexa.Skill.Interaction.Failure

The skill times out or the skill returns an invalid response.

Skill interaction failure event

Alexa.Enterprise.Subscription.Activation

An enterprise subscription is activated for a unit.

Enterprise subscription activation

Alexa.Role.Management.Assignment

A role has been assigned to a principal

Role management event

Alexa.Role.Management.Revocation

A role has been revoked from a principal

Role management event

Alexa.Endpoint.Lifecycle.SetupCompletion

A device has completed retail setup and is ready to be fleet managed

Setup completion event

Automation execution completion event

The following is an example of an automation execution completion event.

{
   "header":{
      "version":"2.0",
      "eventId":{
         "id":"12345-6789-1011-abcd-example"
      },
      "eventType":{
         "namespace":"Alexa.Automation.Execution",
         "name":"Completion"
      },
      "eventTime":{
         "timestamp":"2017-09-20T12:04:03Z"
      },
      "entities": {
         "unit":{
            "type":"Unit",
            "id":"amzn1.alexa.unit.did.12345"
         }
      }
   },
   "payload":{
      "automation":{
         "id":"amzn1.alexa.automation.12345"
      },
      "result": {
        "status": "FAILURE",
      	"errors":[
         {
            "type":"ENDPOINT_NOT_FOUND",
            "message":"Endpoint used in the automation was not found",
            "id":"amzn1.alexa.endpoint.12345"
         }
       ]
     }
   }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All automation-related events share the same namespace. Example: Alexa.Automation.Execution

String

Yes

header.eventType.name

An event name within the namespace. Example: Completion

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.automation

Details for the automation from which the event was generated.

Object

types

payload.automation.id

Unique identifier of the automation instance from which the event was generated.

String

Yes

payload.result

Details about the result of the automation.

Object

Yes

payload.result.status

Status of automation execution initiation or completion. Allowed values:
  • SUCCESS: Automation was triggered and completed successfully.
  • FAILURE: Automation trigger or completion failed.

String enum

Yes

payload.result.errors

Errors that occurred for automation initiation or completion.

Array

No

payload.result.errors[*].type

Error type. Allowed values:
  • ENDPOINT_NOT_FOUND: Endpoint used in the automation wasn't found.
  • INTERNAL_SERVER_ERROR: Internal server error.

String

No

payload.result.errors[*].message

Message that describes the error.

String

No

payload.result.errors[*].id

Endpoint ID. Example: amzn1.alexa.endpoint.12345

String

No

Skill interaction failure event

The following is an example of a skill interaction event that reports a skill fault event due to an invalid response from the skill or a skill endpoint timeout.

{
   "header":{
      "version":"2.0",     
      "eventId":{
         "id":"12345-6789-1011-abcd-example"
      },
      "eventType":{
         "namespace":"Alexa.Skill.Interaction",
         "name":"Failure"
      },
      "eventTime":{
         "timestamp":"2017-09-20T12:04:03Z"
      },
      "entities": {
         "unit":{
            "type":"Unit",
            "id":"amzn1.alexa.unit.did.12345"
         },
         "skill":{
            "type":"Skill",
            "id":"amzn1.ask.skill.12345"
         }         
      }
   },
   "payload":{
      "interaction":{
         "type":"IntentRequest",
         "locale":"en-US",
         "intent":{
            "name":"intentName"
         },
      },
      "skill":{
         "id":"amzn1.ask.skill.12345",
         "stage":"live"
      },
      "unit":{
         "id":"amzn1.alexa.unit.did.12345"
      },
      "session":{
         "id":"amzn1.echo-api.session.12345"
      },
      "requestId":"amzn1.echo-api.request.12345",
      "error":{
         "type":"INVALID_RESPONSE",
         "message":"Details about the error"
      }
   }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All skill interaction-related events share the same namespace. Example: Alexa.Skill.Interaction

String

Yes

header.eventType.name

An event name within the namespace. Example: Failure

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity and Skill entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.interaction

Object that describes the type of skill interaction where failures were observed.

Object

Yes

payload.interaction.type

Type of skill interaction where failures were observed. Allowed values: IntentRequest

String enum

Yes

payload.interaction.locale

User's locale. Example: en-US

String

Yes

payload.interaction.intent

Object that indicates the action that fulfills a user's spoken request.

Object

No

payload.interaction.intent.name

Name of the intent that corresponds to the action the user requested. Example: AMAZON.CancelIntent

String

No

payload.skill

Object that represents the skill to which the event pertains.

Object

Yes

payload.skill.id

Unique identifier of a skill. Example: amzn1.ask.skill.12345

String

Yes

payload.skill.stage

Stage of the skill. Allowed values: development, live, or certification

String

Yes

payload.unit

Object that contains the unit ID.

Object

Yes

payload.unit.id

Unit ID that uniquely identifies a unit.

String

Yes

payload.session

Object that contains an ID that uniquely identifies a skill session.

Object

Yes

payload.session.id

ID that uniquely identifies a skill session. Example: amzn1.echo-api.session.12345. This value might be a session ID you haven't seen before, such as when the first request to a skill fails to reach the skill.

String

Yes

payload.requestId

ID that uniquely identifies an Alexa user request and the response to it. Example: amzn1.echo-api.request.12345-678910-abcdefg

String

Yes

payload.error

Object that contains additional details about the result of the user's request to the skill.

Object

Yes

payload.error.type

Type of error. Allowed values:
  • INVALID_RESPONSE: This can happen when Alexa is unable to understand the skill response (for example, the SSML format in the skill response is invalid) or when Alexa is unable to call the endpoint for some reason (for example, the endpoint is misconfigured, Alexa doesn't have the required permissions, and so on).
  • ENDPOINT_TIMEOUT: Alexa didn't get a response in time.

String enum

Yes

payload.error.message

Description of the error. You should rely on the type of error and not the message of the error. The message is only used for logging purposes.

String

Yes

Enterprise subscription activation event

The following is an example of an enterprise subscription activation event.

{
   "header":{
      "version":"2.0",     
      "eventId":{
         "id":"12345-6789-1011-abcd-example"
      },
      "eventType":{
         "namespace":"Alexa.Enterprise.Subscription",
         "name":"Activation"
      },
      "eventTime":{
         "timestamp":"2017-09-20T12:04:03Z"
      },
      "entities": {
         "unit":{
            "type":"Unit",
            "id":"amzn1.alexa.unit.did.12345",
            "parent": {
               "type":"Unit",
               "id":"amzn1.alexa.unit.did.12345"
            }
         }
      }
   },
   "payload":{        
      "subscription": {
         "id": "amzn1.ask.skill.12345"
      },
      "result": {
         "status": "SUCCEEDED",
         "error": {
            "type": "INTERNAL_SERVER_ERROR",
            "message": "Details about the error"
         }
      }    
   }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All enterprise subscription-related events share the same namespace. Example: Alexa.Enterprise.Subscription

String

Yes

header.eventType.name

An event name within the namespace. Example: Activation

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.subscription

Details of the subscription for which the event was generated.

Object

Yes

payload.subscription.id

ID of the subscription.

String enum

Yes

payload.result

Result of the subscription activation.

Object

Yes

payload.result.status

Status of the subscription activation.

String enum

Yes

payload.result.error

Error that occurred for subscription activation. If activation succeeds, this object won't be present.

Object

No

payload.error.type

Type of error. Allowed values:
  • INTERNAL_SERVER_ERROR: The activation workflow timed out or failed to run.

String enum

Yes

payload.error.message

Description of the error. You should rely on the type of error and not the message of the error. The message is only used for logging purposes.

String

Yes

Role management event

The following is an example of an a role management assignment event.

{
  "header": {
    "version": "2.0",
    "eventId": {
      "id": "12345-6789-1011-abcd-example"
    },
    "eventType": {
      "namespace": "Alexa.Role.Management",
      "name": "Assignment"
    },
    "eventTime": {
      "timestamp": "2017-09-20T12:04:03Z"
    },
    "entities": {
      "resource": {
        "type": "Resource",
        "resourceType": "Unit",
        "resourceId": "amzn1.alexa.unit.did.12345"
      }
    }
  },
  "payload": {
    "operator": {
      "id": "12345",
      "type": "User"
    },
    "role": {
      "id": "amzn1.alexa.role.12345"
    },
    "targetEntity": {
      "id": "amzn1.alexa.unit.12345",
      "type": "Unit"
    },
    "principal": {
      "id": "12345",
      "type": "User"
    },
    "propagationInfo": {
      "timestamp": "2022-08-17T12:19:20.026Z",
      "fromRole": "amzn1.alexa.role.12345"
    }
  }
}

The following is an example of an a role management revocation event.

{
  "header": {
    "version": "2.0",
    "eventId": {
      "id": "12345-6789-1011-abcd-example"
    },
    "eventType": {
      "namespace": "Alexa.Role.Management",
      "name": "Revocation"
    },
    "eventTime": {
      "timestamp": "2017-09-20T12:04:03Z"
    },
    "entities": {
      "resource": {
        "type": "Resource",
        "resourceType": "Unit",
        "resourceId": "amzn1.alexa.unit.did.12345"
      }
    }
  },
  "payload": {
    "operator": {
      "id": "12345",
      "type": "User"
    },
    "role": {
      "id": "amzn1.alexa.role.12345"
    },
    "targetEntity": {
      "id": "amzn1.alexa.unit.12345",
      "type": "Unit"
    },
    "principal": {
      "id": "12345",
      "type": "User"
    },
    "propagationInfo": {
      "timestamp": "2022-08-17T12:19:20.026Z",
      "fromRole": "amzn1.alexa.role.12345"
    }
  }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All role-related events share the same namespace. Example: Alexa.Role.Management.

String

Yes

header.eventType.name

An event name within the namespace. Example: Assignment

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.role

Details for the role that is being assigned/revoked which generates the event.

Object

types

payload.role.id

Unique identifier of the role.

String

Yes

payload.operator

Details about the operator which initiated role assignment/ revocation.

Object

Yes

payload.operator.id

The unique identifier for the operator.

String

Yes

payload.operator.type

The type of the operator. Always "User".

String

Yes

payload.targetEntity

Details about the target entity associated with the roleId for which the respective role assignment/ revocation is made.

Object

Yes

payload.targetEntity.id

The unique identifier for the target entity.

String

Yes

payload.targetEntity.type

The type of the targetEntity. Always "Unit".

String

Yes

payload.principal

Details about the principal identifier for which the role assignment/ revocation is made.

Object

Yes

payload.principal.id

The unique identifier for the principal.

String

Yes

payload.principal.type

The type of the principal. Always "User".

String

Yes

payload.propagationInfo

PropagationInfo is included if the role assignment / revocation request includes the propagation flag. It contains information related to the propagation of the role assignment / revocation.

Object

No

payload.propagationInfo.timestamp

The time at which the propagation was initiated in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

No

payload.propagationInfo.fromRole

The roleId from which the propagation is initiated

String

No

Setup completion event

The following is an example of an a setup completion event.

{
 "header": {
  "version": "2.0",
  "eventId": {
   "id": "12345-6789-1011-abcd-example"
  },
  "eventType": {
   "namespace": "Alexa.Endpoint.LifeCycle",
   "name": "SetupCompletion"
  },
  "eventTime": {
   "timestamp": "2023-01-20T08:02:03Z"
  },
  "entities": {
   "registeredCustomer": {
    "type": "Customer",
    "id": "amzn1.account.12345"
   }
  }
 },
 "payload": {
  "endpoint": {
   "id": "amzn1.alexa.endpoint.12345"
  }
 }
}

Header parameters

Parameter Description Type Required

header.version

Schema version, which is 2.0.

String

Yes

header.eventId

Object that contains the event ID.

Object

Yes

header.eventId.id

Unique identifier that represents an event.

String

Yes

header.eventType

Object that contains the event name and namespace.

Object

Yes

header.eventType.namespace

Represents the category an event belongs to. All role-related events share the same namespace. Example: Alexa.Endpoint.LifeCycle.

String

Yes

header.eventType.name

An event name within the namespace. Example: SetupCompletion

String

Yes

eventTime

Object that contains the event time.

Object

Yes

eventTime.timestamp

Event creation time in "YYYY-MM-DDThh:mm:ssZ" format (RFC 3339 profile of ISO 8601).

DateTime

Yes

entities

List of entities. For details, see Unit entity.

Array

Yes

Payload parameters

Parameter Description Type Required

payload.endpoint

Details for the endpoint (the device) that triggered the event

Object

Yes

payload.endpoint.id

Unique identifier of the endpoint that can be used directly when making an associatedUnits API call to associate the device to a unit.

String

Yes

Entities

The header of the event can have the following entities.

Unit entity

Parameter Description Type Required

unit

Object that represents the details of a unit.

Object

Yes

unit.type

Unit entity type. Valid values: Unit

String enum

Yes

unit.id

Unit identifier.

String

Yes

unit.parent

Parent unit, which contains the parent ID.

Object

Yes

unit.parent.type

Parent entity type. Valid values: Unit

String enum

Yes

unit.parent.id

Parent identifier.

String

Yes

Skill entity

Parameter Description Type Required

skill

Object that represents the details of a skill.

Object

Yes

skill.type

Skill entity type. Valid values: Skill

String enum

Yes

skill.id

Skill identifier.

String

Yes

Resource entity

Parameter Description Type Required

resource

Object that represents the details of the resource.

Object

Yes

resource.type

Resource entity type. Valid values: "Resource"

String

Yes

resource.resourceType

The type of the resource. Valid value: "Unit"

String

Yes

resource.resourceId

The unique identifier for the resource

String

Yes

Was this page helpful?

Last updated: Dec 13, 2023