Send Events to the Alexa Event Gateway

Smart home skills are now called smart home add-ons. No action is needed, and your existing integration will continue to operate normally.

To send a proactive event to Alexa or an asynchronous response to a previous directive, you send an event from your device cloud to the Alexa event gateway. The Alexa.ChangeReport event is the most common proactive event that your smart home add-on sends to the Alexa event gateway.

Note: Before you start this topic, make sure that you understand the account linking flow that happens when a customer enables your add-on. For details, see Add Account Linking.

Follow these guidelines to authenticate your smart home add-on or video skill with the customer account and send asynchronous events to the Alexa gateway.

Prerequisites

To send asynchronous events, your smart home add-on must comply with the following prerequisites:

Configure account linking for your smart home add-on.
To send Alexa.ChangeReport events, set proactivelyReported to true in your discovery response for properties of an interface that you report to Alexa.

Event gateway access

When the customer enables your smart home add-on in the Alexa app, the Alexa service invokes the account linking flow with your OAuth 2.0 provider. Here, the Alexa service obtains tokens to access the customer account in your system. For more details about account linking, see How Users Experience Account Linking.

To send events to the Alexa event gateway, a second OAuth exchange occurs. Your add-on must implement this OAuth exchange with the Amazon OAuth server. The Alexa service starts the authorization flow by sending an Alexa.Authorization.AcceptGrant directive to your add-on. In response, your add-on initiates an authorization-code grant flow with the Login with Amazon (LWA) OAuth server to exchange the code for access and refresh tokens. Your add-on stores the tokens for each Alexa customer in a secure location. Later, when you send events and asynchronous responses to the Alexa event gateway on behalf of the customer, you include the access token. Alexa uses the token to identify the Alexa customer. You can send asynchronous events directly from the device cloud, or from your add-on.

Steps to send events to Alexa

Complete the following steps to enable your add-on to send events and asynchronous responses to the Alexa event gateway on behalf of the customer.

Configure permissions in the Alexa developer console.
Add code to request access to the Alexa event gateway from your add-on.
Add code to send events from your add-on to the Alexa event gateway.

Best practices

To send events and asynchronous responses, implement the following best practices.

Provide a Lambda function for each geographic region where you offer your add-on. In the developer console, on the Build page, configure specific geographic endpoints for each region that you offer your add-on. For details, see Deploy your Lambda function to multiple regions.
Obtain and store customer credentials by region. You implement the authorization code grant flow in a region-specific Lambda function. Store the access tokens so that the region-specific Lambda function can access them.
Send events to the Alexa event gateway endpoint in the same region as your Lambda function on behalf of customers of that region.
To store and send authentication tokens in a secure manner, follow OAuth 2.0 best practices.
Exchange the authorization code for the access and refresh tokens right away. The authorization code has a limited validity period (a few minutes). After the authorization code expires, the customer must disable and enable the add-on again. Re-enabling the add-on generates a new authorization code and prompts Alexa to send the Alexa.Authorization.AcceptGrant directive to your add-on.
You must store the access and refresh tokens for a customer and include the access token in each asynchronous response or event that you send to the Alexa event gateway. Before the token expires, you must use the stored refresh token to get new access and refresh tokens from LWA. Access tokens are typically valid for 60 minutes.

Testing tools

Alexa has multiple tools to help you test and debug state and other events as you build your Alexa smart home add-on. For details, see Test and Debug Your Smart Home Add-on.

Sample code

The following sample code demonstrates how to set up your smart home add-on to send change reports to the Alexa event gateway:

Smart Home Skill Sample: Send Change Report (Python)

Was this page helpful?

Provide feedback

Last updated: Nov 25, 2025