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
• Steps to set up notifications
  • 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
• Which account do I use?
• Troubleshooting

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.
• ASK CLI – This is a tool that you can use to develop and configure Alexa skills by using the command line. You don't need the ASK CLI if you simply want to get notifications for skills that you create for an organization or through an organization's tool, as described previously. However, if you're an independent developer, organization, or tool-builder, you might need the ASK CLI to get an access token that you use when you call SMAPI to set up your notifications. To download and install the ASK CLI, see Quick Start: Alexa Skills Kit Command Line Interface (ASK CLI).

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.

• 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.

How to create an Amazon SNS topic

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.

How to create an IAM role

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.

How to create an SDNS subscriber

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

How to create a subscription to an organization's subscriber

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.

• Skills
• Amazon SNS topic
• IAM role
• Subscriber
• Subscription

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.

• Skills
• Amazon SNS topic
• IAM role
• Subscriber
• Subscription

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.

• Skills
• Amazon SNS topic
• IAM role
• Subscriber
• Subscription

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.

• Skills
• Amazon SNS topic
• IAM role
• Subscriber
• Subscription

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.

• You're using the wrong access token – The access token that you use to update the skill and the access token that you use to create the subscription must be generated from the same LWA security profile.

• Your developer is using the developer console or the wrong access token – For you to receive notifications about skill updates by a developer who works for your organization, 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 using the developer console.

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.

---

---

Last updated: Nov 29, 2023