Use the Alexa Skill Development Notifications

The Skill Development Notifications Service (SDNS) is a message delivery system that enables you to receive notifications about Alexa skill development events that you trigger using the Alexa Skill Management API (SMAPI) or the Alexa Skills Kit Command-Line Interface (ASK CLI). SDNS can also notify you when a customer reviews your skill.

SDNS sends the notifications to an endpoint such as an Amazon Simple Notification Service (Amazon SNS) topic, which then sends the notifications to you. You can choose which type of notifications you receive. For example, you can set up SDNS to send you notifications when your skills pass certification.

You might use SDNS if you're one of the following roles:

• An independent skill developer who wants to get notifications about the skills that you create.
• An organization or tool maker who wants to get notifications about the skills that you or your developers create, and distribute the notifications to your developers.
• A developer who wants to get notifications about the skills that you create for an organization or through an organization's tool.

The following image is a high-level view of where SNDS fits in to the skill-building process.

• Prerequisites
• Notification setup workflows
  • Workflow for independent developers
  • Workflow for organizations and tools with developers
  • Workflow for developers who create skills for an organization or use the organization's tool
  • Step 1: Create an Amazon SNS topic to receive notifications
  • Step 2: Create an IAM role that allows SDNS to publish to the topic
  • Step 3: Create a subscriber
  • Step 4: Create a subscription to skill development events

  Prerequisites

  To set up SDNS to send notifications about skill development events, you must have the following prerequisites:

  • Amazon developer account – To create Alexa skills, you need an Amazon developer account. If you don't already have one, sign up at developer.amazon.com. Every Amazon developer account has a vendor ID. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details. You need this vendor ID when you configure SDNS, as described later.
  • AWS account – You configure SDNS to send notifications to an endpoint, and the available endpoint is currently Amazon SNS. To set up Amazon SNS, you need an AWS account.
  • Access token – To set up and configure SDNS notifications, you must use SMAPI. When you make a request to SMAPI, you must provide an access token as the bearer token in the Authentication header of the request. Keep the access token current by obtaining a refresh token to request a new access token when the access token expires in one hour. Regardless, you can get an access token in one of three ways, depending on the way that you develop Alexa skills:
    • If you're an independent developer or an organization getting an access token for yourself, you 1) create a security profile with LWA, if you don't already have one; 2) copy the client ID and client secret of the security profile from the LWA console; and 3) use the client ID, client secret, and any necessary scopes (including alexa::ask:subscriptions ) to generate an access token by using the ASK CLI generate-lwa-tokens subcommand.
    • If you're an organization getting an access token for a developer who works for you or uses your skill-building tool, you 1) put together a URL for an authorization code grant by using your own client ID and client secret in LWA, including all scopes that the developer requires as well as the SDNS-specific one, which is alexa::ask:subscriptions ; 2) send your developer the URL; 3) after they click the link and successfully log in, receive the authorization code that LWA returns to you; 4) use that authorization code plus your own LWA client ID and client secret to generate an access token; and 5) give that access token to the developer, so that they can use it when they call SMAPI.
    • If you're a developer who creates skills for an organization or you use an organization's tool to develop skills, the organization sends you a URL (as described previously). Click the link and enter the user name and password for your Amazon developer account. After you successfully log in, the organization will send you the access token that you can use with SMAPI.

    Notification setup workflows

    The following sections describe how to set up skill development event notifications depending on what type of developer you are. The first section shows you how to set up skill development event notifications in the simplest scenario. In this scenario, you're an independent developer or an organization setting up notifications for yourself. The last two sections discuss how to set up notifications if you're an organization or tool with developers, or conversely, if you're a developer who works for the organization or uses the organization's skill-building tool.

    Workflow for independent developers

    If you're an independent developer, the workflow to set up notifications is as follows. For detailed information about how to perform the actions, as well as which configuration options to choose, see Steps to set up notifications.

    1. Create an endpoint for the notifications – Set up an endpoint for SDNS to send notifications to. Currently, this endpoint must be an Amazon SNS topic.
    2. Configure the endpoint to distribute notifications – Decide how to distribute the notifications from the endpoint to your users. This is your decision and it depends on your workflow. For example, you might have Amazon SNS send the notifications to you by email.
    3. Authorize SDNS to publish to the endpoint – To do this, you must set up an IAM role and configure it to allow the AWS account of SDNS to publish to your endpoint.
    4. Get an access token – Before proceeding to the next step, make sure that you have an access token as described in Prerequisites. You need this access token to call SMAPI in the next step.
    5. Create an SDNS subscriber – Set up a subscriber by using the Skill Development Notifications API. A subscriber encapsulates the endpoint (Amazon SNS topic) and authorization information (IAM role) that you set up in the previous steps. To create a subscriber, you send a POST request to the subscribers API. For this request, you need the vendor ID of your Amazon developer account, the Amazon resource name (ARN) of the Amazon SNS topic as the endpoint URI, the ARN of the IAM role that you created, and the LWA access token described previously.
    6. Create an SDNS subscription – Set up a subscription by using the Skill Development Notifications API. An SDNS subscription maps the development events that trigger a notification to the SDNS subscriber that receives the notification. To create a subscription, you send a POST request to the subscriptions API. For this request, you need the vendor ID of your Amazon developer account, the ID of the subscriber that you created in the previous step, the list of events that you want to trigger notifications, and the LWA access token described previously.
    7. Receive notifications – If you trigger an event that you specified in your subscription (for example, you submit a skill), you receive an SDNS notification at the Amazon SNS topic that you specified in the subscriber. The event schema defines the format of the notification.

    Workflow for organizations and tools with developers

    If you're an organization with skill developers who work for you (or you made a tool that developers use to create skills), and you simply want to set up notifications about skills that you create under your organization's Amazon developer account, follow the steps for independent developers described previously.

    However, you might also want to receive skill development notifications about skills that your developers create under their own Amazon developer account (that is, their own vendor ID). For you to receive notifications, the developer must use SMAPI or the ASK CLI to work on their skills and they must use the access token that you give them. You don't receive notifications for updates that the developer makes by using the developer console.

    To set up notifications for this workflow, you create the Amazon SNS topic, IAM role, and subscriber as described in the last section. For those steps, make sure to use the vendor ID that is associated with your organization's Amazon developer account. After those steps, the additional work that you must do is as follows:

    • If the developer wants to create a subscription to your subscriber, the developer needs the ID of your subscriber and an LWA access token, which you can generate for them as described in Prerequisites.
    • If, on the other hand, you set up notifications for the developer, use their vendor ID instead of yours when you create the subscription to your subscriber. To find their vendor ID (which must be associated with your organization's Amazon developer account), call the Vendor API.

    For a summary of which account to use in these different cases, see Which account do I use?

    Workflow for developers who create skills for an organization or use the organization's tool

    If you're a skill developer who creates skills for an organization, you might want to receive skill development event notifications about skills that you create under your own Amazon developer account (that is, under your own vendor ID). If you want SDNS to deliver notifications to your own Amazon SNS topic, follow the workflow for an independent developer.

    If, instead, you want SDNS to send notifications to the Amazon SNS topic that the organization set up, you can do so by setting up your own subscription to the subscriber that the organization created. In other words, you don't need to set up an Amazon SNS topic or a subscriber; you just need to create a subscription to a subscriber that the organization created. To enable you to do this, the organization must give you the subscriber ID of the subscriber that they created. The organization must also give you an access token that the organization generated for you with the alexa::ask:subscriptions scope.

    Steps to set up notifications

    The following steps show you how to set up notifications.

    Note: If you create skills for an organization or you use a skill-building tool that the organization created, you can skip to Step 4: Create a subscription.

    • Step 1: Create an Amazon SNS topic to receive notifications
    • Step 2: Create an IAM role that allows SDNS to publish to the topic
    • Step 3: Create a subscriber
    • Step 4: Create a subscription to skill development events

    There are times when you must specify a vendor ID or generate an access token. For a summary of which account to use when doing so, see Which account do I use?

    Step 1: Create an Amazon SNS topic to receive notifications

    Before you configure SDNS to send notifications, you must set up the endpoint that SDNS sends the notifications to. The available endpoint is currently Amazon SNS.

    Note: If you create skills for an organization or you use a skill-building tool that they created, you can skip this step because this step is the organization's responsibility.

    How to create an Amazon SNS topic

    To create and subscribe to an Amazon SNS topic

    1. Log in to your AWS account and navigate to the Amazon SNS console.
    2. On the left, click Topics. On the upper right, click Create topic.
    3. Enter a topic name, and then click Create topic.
    4. To receive notifications as email or SMS messages, subscribe to the Amazon SNS topic.
    5. Make note of the Amazon Resource Name (ARN) for this topic.
       You use it in the next step.

    Step 2: Create an IAM role that allows SDNS to publish to the topic

    The Amazon SNS topic that you created in Step 1 is private to your AWS account. No other entity can publish to that topic. Therefore, your next step is to set up permissions that allow SDNS to publish to the topic. To do so, you create an AWS Identity and Access Management (IAM) role and apply it to SDNS. SDNS can then assume that role whenever it sends a notification to the Amazon SNS topic.

    Note: If you create skills for an organization or you use a skill-building tool that they created, you can skip this step because this step is the organization's responsibility.

    How to create an IAM role

    To create an IAM role for publishing events to your Amazon SNS topic

    1. Log in to your AWS account and navigate to the IAM console.
    2. From the left menu, click Roles, and then, in the middle of the page, click Create role.
    3. For Select type of trusted entity, select Another AWS account.
    4. For Account ID, enter 258925066295.
       That is the AWS account for SDNS.
    5. Select Require external ID.
    6. For External ID, enter the vendor ID for your Amazon developer account.
       To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.

    

    The following screenshot shows the choices that you must make when you configure the IAM role.

  • Click Next: Permissions.
  • Click Create Policy.
    This opens a separate tab where you create a policy to associate with the IAM role that you're creating.
  • On the Create policy page, choose the following options:
    • For Service, select SNS.
    • For Actions, select Publish.
    • For Resources, click Add ARN to restrict access, enter the ARN for the Amazon SNS topic that you created in Step 1, and then click Add.
    • Click Review Policy. Enter a name for your policy, and then click Create policy.
  • Navigate back to the tab in which you're creating an IAM role.
  • Above the Policy table, click the Refresh button to update the list.
  • Search for the policy that you just created.
  • Select the policy, click Next: Tags, and then click Next: Review.
  • Enter a name for the role, and then click Create role.

  Note: SDNS requires the maximum CLI/API session duration of the IAM role to be least one hour. When you create an IAM role, one hour is the default session duration value. Reducing this value might result in periodic notification delivery failures and subscriber deactivations.

  Step 3: Create a subscriber

  In this step, you configure SDNS to send notifications to the Amazon SNS topic by using the IAM role that you created. This information is represented by an SDNS subscriber. You create a subscriber by using SMAPI to call the Skill Development Notifications API, as described in the following procedure.

  Note: If you create skills for an organization or you use a skill-building tool that they created, you can skip this step because this step is the organization's responsibility.

  How to create an SDNS subscriber

  To create a subscriber

  1. Use a REST client to call the following SMAPI endpoint: https://api.amazonalexa.com/v0/developmentEvents/subscribers/ .
  2. As described in Create a subscriber, put the following information in the body of the request:
     • The vendor ID of your Amazon developer account
     • A human-readable name for the subscriber
     • The ARN of the Amazon SNS endpoint, and the IAM role for SDNS to assume to publish to it
  3. As with any request to SMAPI, set the bearer token of the Authentication header of the request to the LWA access token as described in Prerequisites.

  The following example creates a subscriber.

   "name": "Example Development Event Subscriber", "endpoint":  "uri": "arn:aws:sns:us-east-2:000011122233:ExampleSNSTopic", "authorization":  "type": "AWS_IAM", "arn": "arn:aws:iam::000011122233:role/ExampleIAMRole" > >, "vendorId": "M123456EXAMPLE" > 

  If the subscriber details are valid, SDNS creates a subscriber and SMAPI returns HTTP 201 Created . As shown in the following example, the Location header of the HTTP response lists the subscriberId , which is a unique identifier for the subscriber resource.

  Location: /v0/developmentEvents/subscribers/amzn1.ask-subscriber.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 

  When you create an SDNS subscriber, SDNS sends an empty JSON object to the endpoint that you defined in the subscriber. This empty notification enables you to verify that you set up the subscriber correctly. If you set up any form of Amazon SNS topic notification, such as email, mobile SMS, or another channel, you receive this empty object through that channel.

  Important: If SDNS fails to deliver a notification to a subscriber due to a nonexistent endpoint or invalid publishing permissions, the subscriber is marked as inactive. SDNS doesn't deliver future notifications to that subscriber. After you correct the problem, you must call the Update Subscriber API to reactivate the subscriber, even if the credentials haven't changed.

  Step 4: Create a subscription to skill development events

  A subscription maps an Amazon developer account to the subscriber that SDNS sends the notifications to, and specifies which events trigger a notification.

  The way that you set up a subscription depends on whether you created the subscriber. If you're a developer working for an organization or using their skill-building tool, the organization might have created a subscriber for you.

  How to create a subscription to your own subscriber

  To set up notifications to a subscriber that you created

  1. Use a REST client to call the following SMAPI endpoint: https://api.amazonalexa.com/v0/developmentEvents/subscriptions/ .
  2. As described in Create a subscription, put the following information in the body of the request:
     • The vendor ID of your Amazon developer account. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.
     • The ID of the subscriber to create a subscription to.
     • A human-readable name for the subscription.
     • A list of events for which you want to receive notifications.
  3. As with any request to SMAPI, set the bearer token of the Authentication header of the request to the LWA access token as described in Prerequisites.

  The following example creates a subscription for events related to a skill manifest update.

   "name": "Example Development Event Subscription", "events": [ "AlexaDevelopmentEvent.ManifestUpdate" ], "subscriberId": "amzn1.ask-subscriber.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "vendorId": "YOURVENDORID" > 

  If the subscription details are valid, SDNS creates a subscription and SMAPI returns HTTP 201 Created . As shown in the following example, the Location header of the HTTP response lists the subscriptionId , which is a unique identifier for the subscription.

  Location: /v0/developmentEvents/subscriptions/amzn1.ask-subscription.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 

  How to create a subscription to an organization's subscriber

  To set up notifications to a subscriber that you didn't create

  As described in Prerequisites, the organization or tool must first send you a URL for authentication.

  1. Click the URL and enter the user name and password for your Amazon developer account. After you successfully log in, the organization will send you an access token for you to use as the bearer token in the Authentication header of the request. The organization or tool must also send you the subscriber ID of the subscriber that they created for the notifications.
  2. Use a REST client to call the following SMAPI endpoint: https://api.amazonalexa.com/v0/developmentEvents/subscriptions/ .
  3. As described in Create a subscription, put the following information in the body of the request:
     • The vendor ID of your Amazon developer account. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.
     • The ID of the subscriber to create a subscription to.
     • A human-readable name for the subscription.
     • List of events for which you want to receive notifications.
  4. Set the bearer token of the Authentication header of the request to the LWA access token that the organization sent you.

  The following example creates a subscription for events related to a skill manifest update.

   "name": "Example Development Event Subscription", "events": [ "AlexaDevelopmentEvent.ManifestUpdate" ], "subscriberId": "amzn1.ask-subscriber.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "vendorId": "YOURVENDORID" > 

  If the subscription details are valid, SDNS creates a subscription and SMAPI returns HTTP 201 Created . As shown in the following example, the Location header of the HTTP response lists the subscriptionId , which is a unique identifier for the subscription.

  Location: /v0/developmentEvents/subscriptions/amzn1.ask-subscription.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 

  Which account do I use?

  As noted throughout the previous steps, the accounts that you use to set up notifications depend on your workflow. This section summarizes which accounts to use. Choose the workflow that best describes you:

  • Independent developer and want notifications sent to yourself
  • Organization or tool and want notifications about your own skills sent to yourself
  • Organization or tool and want notifications about your developers' skills sent to yourself
  • Developer who creates skills for an organization or uses an organization's tool and you want notifications sent to yourself

  Independent developer and want notifications sent to yourself

  To create skills, Amazon SNS topics, IAM roles, subscribers, and subscriptions, use the following accounts.

  When you create skills, whether using SMAPI or the ASK CLI, use the credentials for your Amazon developer account. Every Amazon developer account has a vendor ID. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details. You need this vendor ID when you configure SDNS.

  When you log in to the Amazon SNS console to create your Amazon SNS topic, use your AWS account.

  When you set up your IAM role, use the following accounts:

  • When you log in to the IAM console to create the IAM role that authorizes SDNS to publish to your Amazon SNS topic, use your AWS account.
  • Set the trusted entity of the IAM role to the AWS account of SDNS (258925066295).
  • Set the external ID of the IAM role to the vendor ID of your Amazon developer account. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.

  When you call SMAPI to create the subscriber, use the following token and vendor ID:

  • Set the bearer token of the Authentication header of the SMAPI request to the access token that you found when you 1) copied the client ID and client secret of your LWA security profile; and 2) used the client ID, client secret, and any necessary scopes (including alexa::ask:subscriptions ) to generate an access token using the ASK CLI generate-lwa-tokens subcommand.
  • Set the vendor ID of the subscriber to the vendor ID of your Amazon developer account. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.

  When you call SMAPI to create the subscription, use the following token and vendor ID:

  • Set the bearer token of the Authentication header of the SMAPI request to the access token that you found when you 1) copied the client ID and client secret of your LWA security profile; and 2) used the client ID, client secret, and any necessary scopes (including alexa::ask:subscriptions ) to generate an access token using the ASK CLI generate-lwa-tokens subcommand.
  • Set the vendor ID of the subscription to the vendor ID of your Amazon developer account. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.

  Organization or tool and want notifications about your own skills sent to yourself

  To create skills, Amazon SNS topics, IAM roles, subscribers, and subscriptions, use the following accounts.

  When you create skills, whether using SMAPI or the ASK CLI, use the credentials for your organization's Amazon developer account. Every Amazon developer account has a vendor ID. To find your organization's vendor ID, log in to your organization's Amazon developer account, and then go to Customer Details. You need this vendor ID when you configure SDNS.

  When you log in to the Amazon SNS console to create your Amazon SNS topic, use your organization's AWS account.

  When you set up your IAM role, use the following accounts:

  • When you log in to the IAM console to create the IAM role that authorizes SDNS to publish to your Amazon SNS topic, use your organization's AWS account.
  • Set the trusted entity of the IAM role to the AWS account of SDNS (258925066295).
  • Set the external ID of the IAM role to the vendor ID of your organization's Amazon developer account. To find your organization's vendor ID, log in to your organization's Amazon developer account, and then go to Customer Details.

  When you call SMAPI to create the subscriber, use the following token and vendor ID:

  • Set the bearer token of the Authentication header of the SMAPI request to the access token that you found when you 1) copied the client ID and client secret of your LWA security profile; and 2) used the client ID, client secret, and any necessary scopes (including alexa::ask:subscriptions ) to generate an access token using the ASK CLI generate-lwa-tokens subcommand.
  • Set the vendor ID of the subscriber to the vendor ID of your organization's Amazon developer account. To find your organization's vendor ID, log in to your organization's Amazon developer account, and then go to Customer Details.

  When you call SMAPI to create the subscription, use the following token and vendor ID:

  • Set the bearer token of the Authentication header of the SMAPI request to the access token that you found when you 1) copied the client ID and client secret of your LWA security profile; and 2) used the client ID, client secret, and any necessary scopes (including alexa::ask:subscriptions ) to generate an access token using the ASK CLI generate-lwa-tokens subcommand.
  • Set the vendor ID of the subscription to the vendor ID of your organization's Amazon developer account. To find your organization's vendor ID, log in to your organization's Amazon developer account, and then go to Customer Details.

  Organization or tool and want notifications about your developers' skills sent to yourself

  To create skills, Amazon SNS topics, IAM roles, subscribers, and subscriptions, use the following accounts.

  When your developers create skills, whether using SMAPI or the ASK CLI, they use access tokens that you generate from the same LWA security profile that generated the access token that you used to set up the subscriber.

  Note: You don't receive notifications for skill updates that your developers make using the developer console.

  When you log in to the Amazon SNS console to create your Amazon SNS topic, use your organization's AWS account.

  When you set up your IAM role, use the following accounts:

  • When you log in to the IAM console to create the IAM role that authorizes SDNS to publish to your Amazon SNS topic, use your organization's AWS account.
  • Set the trusted entity of the IAM role to the AWS account of SDNS (258925066295).
  • Set the external ID of the IAM role to the vendor ID of your organization's Amazon developer account. To find your organization's vendor ID, log in to your organization's Amazon developer account, and then go to Customer Details.

  When you call SMAPI to create the subscriber, use the following token and vendor ID:

  • Set the bearer token of the Authentication header of the SMAPI request to the access token that you found when you 1) set up your organization's security profile in Login with Amazon (LWA); 2) copied the client ID and client secret of your organization's LWA security profile; and 3) called the ASK CLI generate-lwa-tokens subcommand.
  • Set the vendor ID of the subscriber to the vendor ID of your organization's Amazon developer account. To find your organization's vendor ID, log in to your organization's Amazon developer account, and then go to Customer Details.

  When you call SMAPI to create the subscription, use the following accounts:

  • Set the bearer token of the Authentication header of the SMAPI request to the access token that you found when you 1) set up your organization's security profile in Login with Amazon (LWA); 2) copied the client ID and client secret of your organization's LWA security profile; and 3) called the ASK CLI generate-lwa-tokens subcommand.
  • Set the vendor ID of the subscription to the vendor ID of your developer's Amazon developer account. To find their vendor ID (which must be associated with your organization's Amazon developer account), call the Vendor API.

  Developer who creates skills for an organization or uses an organization's tool and you want notifications sent to yourself

  To create skills and subscriptions, use the following accounts.

  When you create skills, whether using SMAPI or the ASK CLI, use the credentials for your Amazon developer account and the access token that the organization provided.

  Note: The organization doesn't receive notifications for skill updates that you make using the developer console or a different access token.

  N/A. In this case, the organization creates the Amazon SNS topic.

  N/A. In this case, the organization creates the IAM role.

  N/A. In this case, the organization creates the subscriber.

  When you call SMAPI to create the subscription, use the following token and vendor ID:

  • Set the bearer token of the Authentication header of the SMAPI request to the access token that the organization sent you. The organization should have sent you the access token after you clicked on the URL that they gave you and you entered the user name and password for your Amazon developer account.
  • Set the vendor ID of the subscription to the vendor ID of your Amazon developer account. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.

  Troubleshooting

  If you subscribed to skill development notifications but you don't receive notifications, review the following list of possible causes.

  If you created the subscriber, check for the following problems:

  • Notification delivery failure – If SDNS fails to deliver a notification to a subscriber, the subscriber is marked as inactive and SDNS doesn't deliver future notifications to that subscriber. You, the subscriber owner, must correct the problem, and then call the Update Subscriber API to reactivate the subscriber, even if the credentials haven't changed. The following issues can cause notification delivery failures:
    • The Amazon SNS topic does not exist – Use the Amazon SNS console to verify that the topic still exists. If you create a new topic, you must then call the Update Subscriber API to reactivate the subscriber.
    • The IAM policy is incorrect – Use the IAM console to verify that the IAM policy that you used to create the subscriber has the correct permissions. For the correct permissions, see Step 2: Create an IAM role that allows SDNS to publish to the topic. After you fix the IAM policy, you must then call the Update Subscriber API to reactivate the subscriber.

    If you created a subscription to a subscriber that you didn't create, check for the following problems:

    • You're using the developer console or the wrong access token – To receive notifications for a subscription to a subscriber that you didn't create, you must update your skill using SMAPI or the ASK CLI, using the access token that the organization gave you.