Send Events to the Event Gateway

Usually when you respond to Alexa, you reply synchronously, which means that you send an event from your Lambda function to Alexa. In some cases you have the option, and in some cases you are required, to reply asynchronously, which means that you send a response event from your device cloud to the Alexa event gateway. For more details about the difference between synchronous, asynchronous, and deferred responses, see Alexa.Response Interface.

This documentation explains what you include in a message to the Alexa event gateway, and where you send it.

Event endpoints, Lambda functions and customer credentials

When you send a message to the Alexa event gateway, send it to the event endpoint that aligns with the geographic availability of your smart home skill. Following is the list of endpoints and the regions they cover.

  • North America:
  • Europe:
  • Far East:

You must:

  • Provide a Lambda for each geographic region where your skill requires permissions. Enable this by picking geographic endpoints on the Build page for your skill in the developer console. Provide ARNs for each region you select.
  • Obtain and store customer credentials by region, meaning if you receive an AcceptGrant request to a region-specific Lambda function, you store the credentials so that they can be accessed by the same Lambda.
  • Communicate with the endpoint in the same region as your Lambda function on behalf of customers for that region

For example, if you offer a skill that sends change report events in the US and the UK, you must configure Lambdas for both North America and Europe. An AcceptGrant request for a US customer is sent to your skill's North America Lambda. You complete the authorization flow with LWA and store the token for that customer so it can be accessed by your skill's North America Lambda. You send events for that customer to For a UK customer, the AcceptGrant is sent to the Lambda configured for Europe and you store and send events the Europe endpoint.

In addition, if a customer moves between geographic regions, they have to re-enable and relink their skill so that your skill knows to change where their information is stored.

The following image shows the process of authenticating a customer and sending messages on their behalf to the Alexa event gateway.

Message contents

You communicate asynchronous messages to Alexa by sending HTTP POST messages to the Alexa event gateway. When you send a message to the Alexa event gateway, include the following:

  • An authorization header containing the bearer token that's also included in the scope property of the message.
  • A content-type header indicating the content type is JSON
  • A JSON-formatted message body.

The body of the message depends on the type of message, for example discovery response, directive response, change report, or other type of message.

  • An endpoint object that contains two pieces of identifying information:

Following is an example of how a message to the event gateway might look:

POST /v3/events HTTP/1.1
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

  "context": {
    "properties": [
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
       "endpointId" :  "endpoint-id"
    "payload": {

Event gateway success codes

The following table lists the success status codes you can receive from the Alexa event gateway.

HTTP response status code Description
202 Accepted The request is authorized and the message is a syntactically valid event. The event has been accepted for further logical validation and processing.

Event gateway error codes

When you receive an error code from the Alexa event gateway, retrieve the code and description fields from the payload to get more information about the error. Use the code field for logging only. Don't use the code field to program business logic.

The following is an example of an HTTP 400 error from the Alexa event gateway:

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  "payload": {
    "description": "The request was malformed"

The following table lists the error status codes you can receive from the Alexa event gateway.

HTTP status Payload code Description

400 Bad Request


The message is invalid due to missing fields, incorrect values, or malformed JSON. Check your messages against the documentation to verify that your message contains all the required fields.

401 Unauthorized


The access token is invalid, expired, or malformed. Refresh your token and retry the request. If a user disables your skill, that also invalidates the access token. This means the user has revoked authorization, and you can stop sending change reports for them.

403 Forbidden


Make sure that you're sending the events to the correct regional endpoint. For example, send events in North America to the North American endpoint.

403 Forbidden


The token doesn't have the required permissions. Make sure that the skill has permission to send Alexa events. For details, see Steps for Asynchronous Message Authentication.

404 Not Found


The account record associated with this directed identifier doesn't exist or has expired. This error can occur if the event was sent too late or with an invalid directed identifier. Please verify that the directed identifier and authorization code are correct.

404 Not Found


The skill ID associated with this token wasn't found. This error occurs when user's access token was generated when the skill was in different stage, such as certification. Try disabling and re-enabling the skill for this user.

413 Payload Too Large


The size of the event payload is too large. The maximum number of endpoints allowed in a request is 300. Send your message with smaller payloads.

429 Too Many Requests


The number of requests is too high. Resend the message up to three times, with at least a one-second interval between each send attempt.

500 Internal Server Error


An error occurred with Alexa, and the message couldn't be processed. Resend the message up to three times, with at least a one-second interval between each send attempt. If problems persist, contact Amazon Support.

503 Service Unavailable


Alexa couldn't accept the message. Resend the message up to three times, with at least a one-second interval between each attempt. If the problem persists, contact Amazon Support.

Testing tools

There are multiple tools to help you test and debug state and other events as you build your Alexa Smart Home skill. For details, see Debug Your Smart Home Skill.

Testing messages

Because events sent to the Alexa event gateway can affect the display in the Alexa app, you must make sure events you send Alexa are well formatted and contain the correct credentials. Use the resources provided in the Alexa Smart Home GitHub repo to create unit tests and test scripts that validate these messages before you send them.