Send Events to the Event Gateway

When you respond to Alexa, you have the option of responding to the Alexa event gateway. This document covers what is included in a message and where you send it.

Event endpoints, Lambda functions and customer credentials

When you send a ChangeReport, asynchronous Response, or proactive discovery event to Alexa, you should communicate with the event endpoint that aligns with the geographic availability of your smart home skill(s). Following is the list of endpoints and the regions they cover.

  • North America: https://api.amazonalexa.com/v3/events
  • Europe: https://api.eu.amazonalexa.com/v3/events
  • Far East: https://api.fe.amazonalexa.com/v3/events

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 https://api.amazonalexa.com/v3/events. 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.

Type of messages you can send

The following table describes some of the scenarios and message types you can send to the Alexa event gateway.

Scenario Message Name
Asynchronous response to a directive Response, after sending a synchronous DeferredResponse
Proactive notification of property value changes ChangeReport
Notify Alexa of a new security camera media recording MediaCreatedOrUpdated
Notify Alexa that a security camera media recording was deleted MediaDeleted
Notify Alexa to send a Wake-on-LAN message to a device that supports powering on by Wake-on-LAN WakeUp

Message contents

You communicate the asynchronous responses and change report events 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 could contain one of the following depending on the purpose of the 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
Host: api.amazonalexa.com
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.

Success

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.

Errors

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. See the asynchronous response example, change report example, and the validation schema.
401 Unauthorized INVALID_ACCESS_TOKEN_EXCEPTION Access token that was provided is not valid; either it is expired token or malformed token. Refresh your token and retry the request.
403 Forbidden SKILL_DISABLED_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. If you are sending events to the correct endpoint, but continue to receive this error, then you can assume the skill has been disabled for this user. This means the user's authorization has been revoked and you can stop sending change reports for them.
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": {
    "code": "INVALID_REQUEST_EXCEPTION",
    "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.

Event responsiveness

When you receive a directive, you can send a synchronous response or a DeferredResponse indicating you received the directive, and later follow up with an asynchronous event to the Alexa endpoint. In either case, there is a hard limit of 8 seconds before Alexa times out.

Known exceptions to the 8 second limit are:

Capability Interface Notes
LockController With slower locks, specify the expected deferral of the Response with the estimatedDeferralInSeconds in the DeferredResponse.