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 information about the difference between synchronous, asynchronous, and deferred responses, see Alexa.Response Interface.

This document 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 will have to re-enable and relink their skill so you will know 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 that is appropriate for your skill. For a list of endpoints, see Alexa event endpoints.

You will include:

  • An authorization header containing the bearer token that is 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": {

Success response and errors

When you send a message to the Alexa event gateway, you should either receive an 202 Accepted response, which indicates the message has been accepted for processing, or an error. The following tables lists the responses you could receive, notes and possible solutions for error conditions.


HTTP Response type Notes
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.


When you receive an error response, you should retrieve the payload code field to determine the cause of the error. The payload will also contain a description field, but you should use this field for logging only and not base any business logic on this field. The following table lists the possible HTTP response types, the associated error codes, and tips for resolving the error.

HTTP Response type Payload error code Notes and possible solutions
400 Bad Request INVALID_REQUEST_EXCEPTION The message was not valid, possibly due to missing required fields, incorrect values, or malformed JSON. Check your messages against the documentation to ensure your events contain all of the required fields.
401 Unauthorized INVALID_ACCESS_TOKEN_EXCEPTION Access token that was provided is not valid; it is an expired or malformed token. Refresh your token and retry the request in this case. A user disabling the skill associated with a token will also invalidate the token. This means the user's authorization has been revoked and you can stop sending change reports for them.
403 Forbidden SKILL_NEVER_ENABLED_EXCEPTION Ensure that you're sending the events to the correct regional endpoint. For example, events in North America should be sent to the North American endpoint.
403 Forbidden INSUFFICIENT_PERMISSION_EXCEPTION The token does not have the required permissions. Make sure the skill has permission to send Alexa events. See Steps for Asynchronous Message Authentication.
404 Not Found SKILL_NOT_FOUND_EXCEPTION The skill ID associated with this token could not be found. This error occurs when user's access token was generated when the skill was in different state, such as the certification stage. Try disabling and re-enabling the skill for this user.
413 Payload Too Large REQUEST_ENTITY_TOO_LARGE_EXCEPTION The size of the event payload is too large. The maximum number of endpoints allowed in a request is 300. Send requests with smaller payloads.
429 Too Many Requests THROTTLING_EXCEPTION The number of requests is too high. Resend the message up to 3 times, with at least a 1 second interval between each send attempt.
500 Internal Server Error INTERNAL_SERVICE_EXCEPTION An error occurred with Alexa, and the message could not be processed. Resend the message up to 3 times, with at least a 1 second interval between each send attempt. If problems persist, contact Amazon Support.
503 Service Unavailable SERVICE_UNAVAILABLE_EXCEPTION Alexa could not accept the message. Resend the message up to 3 times, with at least a 1 second interval between each send attempt. If problems persist, contact Amazon Support.

Following is an example of an HTTP 400 error:

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"

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. If your message is malformed, it can be rejected from the endpoint. Use the resources provided in the Alexa Smart Home GitHub repo to create unit tests and test scripts that validate these messages prior to sending them.

Testing phase and tool

We have developed tools for developers who are sending proactive state updates (ChangeReport events), and you can use them to assist you in identifying issues that might be affecting the accuracy of your proactive state updates. For more information about the tools, see Debug Your Smart Home Skill.