Forem: Seth Carney

Build Multi-Channel Notifications in Your AWS Stack using a Node.js Example

Seth Carney — Mon, 13 Sep 2021 18:53:41 +0000

How to Set Up Multi-Channel Notifications in Your AWS Stack
In this article, we’ll walk through an example architecture for building your own notification service with AWS, and show you how to implement it in Node.js. We’ll also discuss a few considerations related to using AWS services for notifications.

Let’s dive in!

Why build multi-channel notifications?

Notifications are core to many software products today, from apps to e-commerce stores. For example, Instagram would not last without notifications, since users would probably not keep it open just to monitor activity.

Multi-channel notifications become a strategic concern when companies realize that they cannot cater to their users, who are present on a variety of channels, with a one-size-fits-all approach. For instance, a user might prefer a summary of travel forum activity over email, since it works well for asynchronous communication. But for an activity requiring immediate attention, like a change to a flight schedule, a company would likely trade the email notification for a push notification, which the person concerned would likely see sooner.

Ultimately, multi-channel notifications can affect your bottom-line: companies that tailor their notifications based on user needs tend to enjoy higher user engagement.

Why use AWS services for multi-channel notifications?

If you’re building multi-channel notifications into your project, the main reason you might go with AWS services is if you’re already using AWS for the rest of your infrastructure. If you already have AWS experience, it makes sense to build notifications in AWS since you’ll already be familiar with the AWS APIs and know your way around the AWS Management Console.

Amazon Web Services offers two products for end-user notifications: SES and SNS. Both services have a pay-per-use pricing model that’s ideal for companies that want to start small and scale up their AWS use as the business grows.

Amazon Simple Email Service (SES) is an API for sending emails and managing email lists. SES’s main API endpoints are focused on sending emails and managing email contacts. The service also includes more advanced endpoints related to deliverability, like managing the dedicated IP addresses from which SES sends your emails.

Amazon Simple Notification Service (SNS) is an API for sending notifications to applications and people. For many developers, the key to SNS is the “people” part—ability to send push and SMS messages to customers. SNS’s API endpoints allow you to send individual messages, but most of the service’s functionality is built around SNS topics for sending batches of notifications over time.

Multi-channel notification system architecture for AWS

AWS SES and SNS provide APIs for sending notifications, but it's still the developer's job to tell the services which notifications to send, and to whom.

Here's an example architecture for building out a notification system for AWS:

A common pattern in a service-oriented architecture is to extract notification logic to create a standalone service. In our example architecture, the notification service contains a few core pieces of functionality:

Templates: most notifications you send follow a standardized format. Templates allow you to create that format once and then replace placeholders with user information.
Error handling: when a notification cannot be delivered, whether because the end user is unreachable or the notification APIs are down, you’ll likely need to try and resend the notification.
Preferences: you’ll need to store user choices for message categories such as account-related notifications or marketing messages.
User profiles: you’ll want to store user emails and phone numbers.
Notification routing: this is the core logic for deciding which notification should be sent based on event type, user preference, user location, and other factors.
Tracking: to analyze the effectiveness of your notifications, you’ll need to track interactions with individual notifications.

The notification service usually needs to expose an API to which other services can connect. The API can be synchronous, available through an HTTP REST or GRPC endpoint, or asynchronous and based on a message broker, like RabbitMQ.

Beyond the code in the notification service itself, developers often need to collect metrics in a centralized metrics store. Team members in charge of the notification service track the service’s status through metrics like the number of notifications sent per hour, or the share of API errors from various providers. If the service has a queue-based API, the queue size would also be published as a metric. Service operators could use these metrics to understand whether the service is behaving normally, or if there are issues requiring attention from the development team.

While the service connects to third-party notification-sending services (SES and SNS, in our case), you can extend it to support other providers in the future.

Sample implementation of a notification service

Let’s walk through a notification service implementation in code. For this example, we’ll go with a Node.js web framework called Fastify. It’s a lightweight framework that’s optimized for speed, which is exactly what we need in an internal REST service.

We’ll implement a REST API as our interface to the notification service, but your implementation can have a different structure—it can be a GRPC API, or it can consume messages off of a RabbitMQ queue.

In case you’d like to follow along, our complete example implementation is available in the notification-service repository on GitHub.

We start by cloning the repo and installing all required dependencies:

$ git clone git@github.com:/trycourier/aws-notification-service.git
$ cd notification-service
$ npm install

The logic of our example notification service is contained in the fastify/index.js file.

Now we'll define an email template. We’ll use AWS SES’s built-in template functionality, but you could use a library like mustache.js or build your own templating system instead. Our template map contains the fields that SES requires in their API:

// fastify/index.js
const paramsForTemplateCreation = {
  Template: {
    TemplateName: 'MigrationConfirmation',
    HtmlPart: "<h1>Hello {{name}},</h1><p>You are confirmed for the winter migration to <a href='https://en.wikipedia.org/wiki/{{location}}'>{{location}}</a>.</p>",
    SubjectPart: 'Get ready for your journey, {{name}}!',
    TextPart: "Dear {{name}},\r\nYou are confirmed for the winter migration to <a href='https://en.wikipedia.org/wiki/{{location}}'>{{location}}</a>"
  }
}

We’ll need to create this template on AWS, so we’ll add a function for creating a template using the AWS SDK:

async function createTemplate (params) {
  try {
    const data = await sesClient.send(new CreateTemplateCommand(params))
    console.log('Success', data)
  } catch (err) {
    console.log('Error', err.stack)
  }
}

We’ll get an error if we try to create a template that already exists in the system, so we wrap the createTemplate() function in a try/catch block. In this block, we’ll try to get the template with the relevant name, and if that fails we’ll create it in AWS:

async function createTemplateIfNotExists (params) {
  try {
    const queryParams = { TemplateName: params.Template.TemplateName }
    const templateExists = await sesClient.send(new GetTemplateCommand(queryParams))
  } catch (err) {
    createTemplate(params)
  }
}

We won’t add many other features to our simple templating system for now.

Next, let’s take care of the notification sending. Because we’re using AWS SES templates, it makes sense to use the SES sendTemplatedEmail endpoint:

async function sendTemplatedEmail (params) {
  try {
    const data = await sesClient.send(new SendTemplatedEmailCommand(params))
    console.log('Success.', data)
    return data // For unit tests
  } catch (err) {
    console.log('Error', err.stack)
  }
}

In this function, we’ll simply pass the parameters that we receive to the sendTemplatedEmail API endpoint. Let’s also create a set of placeholder parameters so that we can easily call the sendTemplatedEmail function when we need to:

const paramsForTemplatedEmail = {
  Destination: {
    ToAddresses: [
      'kingfisher@example.imap.cc'
    ]
  },
  Source: 'nightjar@example.imap.cc',
  Template: 'MigrationConfirmation',
  TemplateData: '{ "name":"Alaric", "location": "Mexico" }' /* required */,
  ReplyToAddresses: []
}

Now it’s time to define the API routes that our services will use to send notifications. We define the main route, /notify, by using Fastify’s URL shorthand:

const app = fastify({ logger: true })

app.post('/notify', async (req, res) => {
  const { userId, event, params } = req.body
  switch (event) {
    case 'migration-confirmed':
      sendTemplatedEmail(paramsForTemplatedEmail)
      res.send('migration-confirmed email sent')
      break
    default:
      res.send('event not configured')
  }
})

Here, we’re defining the POST /notify endpoint. Once the application receives a request to the /notify URL, it’ll parse out the following elements from the request body:

userId: an internal user identifier.
event: an event type requiring user notification.
params: any additional parameters for building out notification contents.

Based on the event value, we’ll need to decide which notification to send. Some products will have complex notification routing logic, but we’ll start with a single switch statement. A long switch statement will become unmaintainable if you add many events, so this section should eventually be split into multiple functions.

We only have migration-confirmed defined for now, and when that event occurs we want to send an email notification. Other calls to services, like AWS SNS, would go inside the statement that handles the migration-confirmed event.

Beyond the /notify endpoint above, we can create additional endpoints as needed. For example, here are a few endpoints that your notification service will need (we’ll leave implementation up to you):

app.post('/subscriber', async (req, res) => {
  const { userId, email, phoneNum } = req.body
  // handle new subscribers
  res.send('handling of new subscribers not yet implemented')
})

app.delete('/subscriber/:userId', async (req, res) => {
  const userId = req.params.userId
  // unsubscribe user identified by userId from all emails
  res.send('handling of unsubscribes not yet implemented')
})

app.put('/subscriber/:userId/preferences', async (req, res) => {
  const { preferences } = req.body
  // handle subscription preferences
  res.send('handling of preferences not yet implemented')
})

Finally, we tell our Fastify backend to listen on port 3000:

const server = app.listen(3000, () => console.log('🚀 Server ready at: http://localhost:3000'))

Let’s start the app and try it out:

$ npm run dev
[nodemon] starting `node fastify/index.js`
{"level":30,"time":1628785943753,"pid":16999,"hostname":"notification-service","msg":"Server listening at http://127.0.0.1:3000"}
🚀 Server ready at: http://localhost:3000

Now we’ll try issuing a POST request to the /notify endpoint. We’ll use cURL for this purpose, but you can also use an app like Postman:

$ curl -X POST \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \
   -d '{"userId": 123, "event": "migration-confirmed"}' \
   localhost:3000/notify

We can see the notification email land in our inbox shortly after calling the endpoint:

Email notification in our test inbox.

Nice work! We now have a working notification service with AWS.

Limitations to AWS notification solutions

Before you jump into the design and implementation phases for your AWS-backed notification service, consider the following limitations to AWS services.

AWS services are “raw”

Think about SES and SNS as services with APIs closely resembling the underlying notification protocols. Both services will require you to implement most features that are not core to notification sending.

For example, SES requires you to manually compose multi-part messages if you’re looking to send attachments. It does not offer a seamless API that would automatically take care of the attachments—you’ll need to implement that yourself on top of the SES API.

Contact management is another area in which SES requires additional work. If you opt for SES-managed lists, you’ll need to build the logic for adding and removing subscribers for each email list.

SNS is also limited in terms of developer usability. For example, notifications that cannot be delivered end up in a dead-letter queue, which you’ll need to monitor for retries.

Error-checking is laborious

Another aspect of AWS’s “rawness” is error-checking. For example, you need to check for email bounces or undelivered push notifications and manage them yourself.

As we mentioned above, any SNS notification that cannot be delivered will end up in a dead-letter queue. This queue is an Amazon Simple Queue Service (SQS) queue, and you’ll need to implement functionality to listen for messages on this channel.

When you get an “unsuccessful notification” message in this queue, you’ll need to decide whether to try the notification again (and schedule it in your notification service accordingly), or to send it through an alternative notification method (a different channel or provider). You’ll also need to track which push targets and email addresses are consistently unresponsive and thus need to be removed from future notification lists.

You can build error-handling functionality with SNS and SES, as the necessary details for each error case are available on both services’ APIs. But you’ll also need to implement error handling yourself.

You’ll need to build a templating engine

While you can readily implement simple email and notification templates using tools like mustache.js, complex templates, like elaborate HTML emails, are another story.

You’ll need to test your templates to ensure they work as expected on all supported devices and clients. Email formatting is difficult to get right, so we recommend budgeting extra time to develop and test your templates.

How Courier improves the notification experience for AWS-based customers

Courier is an API for multi-channel notifications, and many of our customers use AWS. We offer our customers an opportunity to use AWS services for notifications without having to build all of the additional functionality on top of AWS services themselves.

Here's how you might send an email and SMS notification with Courier:

import { CourierClient } from "@trycourier/courier";

const courier = CourierClient({ authorizationToken: "<AUTH_TOKEN>" }); // get from the Courier UI

// Example: send a message supporting email & SMS
const { messageId } = await courier.send({
  eventId: "<EVENT_ID>", // get from the Courier UI
  recipientId: "<RECIPIENT_ID>", // usually your system's User ID
  profile: {
    email: "kingfisher@example.imap.cc",
    phone_number: "555-228-3890"
  },
  data: {} // optional variables for merging into templates
});

Courier handles all communication with AWS on the backend and offers a number of additional advantages to reduce your implementation work:

Notification Designer: we offer a web interface for designing notification templates, allowing users to create and edit notification templates without redeploying any code. This reduces the engineering work required to get new notifications added to a product.
Automated handling of unsubscribes and errors: Courier handles notification preferences and automatically adjusts notification flows for unsubscribing users. There’s no need to monitor dead-letter SQS queues.
Multi-provider: down the line, you may want to switch from SNS and SES, or add an additional provider for sending international SMS messages. Courier integrates with 20+ providers, all using the same API.

Conclusion

In this article, we presented our suggested notification service architecture for integrating with AWS SES and SNS.

It’s easy to get started with Courier to orchestrate notifications in your AWS services.

We’re offering a free plan with up to 10,000 notifications/month, and we don’t require your credit card to get started.

Why we are moving off REST and implementing GraphQL

Seth Carney — Tue, 24 Nov 2020 19:38:17 +0000

Why we decided to transition to GraphQL

When we started building Courier, we investigated GraphQL, but the options for running a serverless version of Apollo (the technology we wanted to use) were limited and less stable. Because we don’t run EC2 or have dedicated servers, that was a major consideration for us. However, that’s changed quite substantially since we first looked at Apollo. Since then, we’ve been able to start transitioning both our internal and external APIs to GraphQL.

I’ll explain the reasoning behind this below.

Limitations of using REST

REST has been around for a long time, and today it’s still the most widely-accepted way to write an API. REST is a specification that sits on top of HTTP. API calls are structured around objects (like profiles, preferences, and templates) using dedicated HTTP endpoints. For example, if you wanted to expose a way to programmatically manipulate your user profiles, you might have a REST endpoint /user/{userId} which can be queried to perform CRUD operations using HTTP GET, POST, DELETE, etc. Writing a REST API is pretty straightforward – but REST can be tricky to use as an API consumer.

First, REST wasn’t designed for complex sequences of operations that don’t fit neatly into the CRUD bucket. It’s not easy to update two objects at the same time, for example, and even retrieving data in certain scenarios can require multiple calls and branching logic as one endpoint might have to call another one. Another downside of REST is it puts a lot of responsibility on the API consumer (which may be your internal developers or your customers) to know how the underlying data is structured. That’s not optimal for several reasons.

The API calls aren’t oriented to the common actions that the user wants to take. They’re structured rigidly around your objects. That means someone might have to call the same REST endpoint to set a label and add a collaborator, even though these are two completely different use cases. Another reason it’s not a good idea to structure your API around how your data is organized is because things change. Changes to your data are inevitable and it’s hard to adapt REST APIs to these changes (if you do find yourself in this situation, here's how we approached standardizing our REST API).

Advantages of moving to GraphQL

GraphQL is a query language with a very developer-friendly approach to building APIs. It's based on the idea that the API consumer shouldn’t have to know anything about how the data is stored internally. Instead, you describe your data’s relational schema and the consumer can query that nested data from a single endpoint that never changes. GraphQL also conforms to the idea of CQRS, or command-query responsibility separation – put simply, it means the way that you query data is different from the way you mutate data.

One of the things I like best about GraphQL is, as a side effect of implementing it, you’re forced to live by some of those rules of software engineering that you really should be living by. You have to think about your data holistically and you don’t end up with a bunch of poorly-designed endpoints lying around as the result of shortcuts you took to meet deadlines.

Because of how it’s built, GraphQL is really good at versioning: you can mark functionality as deprecated and you can change the underlying infrastructure without breaking existing integrations (and without the consumer even knowing). GraphQL also has a solid caching layer, which reduces our total operational costs because we end up not hitting our database as much. Because we’re a serverless shop, we will actually be implementing our caching layer through ElastiCache.

Using GraphQL at Courier

How we decided which technology to use

As I mentioned earlier, we thoroughly researched the options for implementing GraphQL and kept an eye on possible solutions. There were two main options that emerged for our use case: AWS AppSync and Apollo GraphQL.

We evaluated AppSync because we’re an AWS customer, we use cloud formations, and it was appealing to be able to stand something up quickly. But there were some core security choices we made when implementing multi-tenancy in Amazon Cognito that made the switch to AppSync difficult. We realized AppSync wasn’t going to work for us unless we changed some of those fundamental decisions.

But that wasn’t the only reason we decided to go with Apollo. Compared to AppSync, which uses the Apache Velocity Template Language (VTL), Apollo is just JavaScript. When we work with Apollo, we don’t have to do a lot of the mental context-switching that happens when you use different languages. Not to mention, Apollo is popular for a reason: it’s a rock-solid product that’s constantly evolving and has a growing and supportive community of users. Finally, we chose Apollo for the Apollo Federation, which will help us grow our Graph without affecting our performance as our product scales.

Our roadmap for transitioning to GraphQL

Right now, we’ve moved some of our internal APIs to GraphQL, such as the infrastructure for accessing users and tenants. We’re also building all new features with GraphQL as well.

While it'll be some time before we move all our internal APIs to GraphQL, we have plenty of important candidates for this transition. One key use case is autosave during template creation in our notifications designer. When you're editing a template, you can add content blocks like text or images, add notification channels like email or SMS, and add conditional logic (just to name a few examples) and, as soon as you make a change, it gets autosaved. Behind the scenes, these edits are funneled through a common processor.

One of the problems in REST is it’s difficult to do partial updates. The various components end up having to send the whole template resource when they want to update a single field. Sure, you can implement PATCH endpoints, but those come with their own complications. When you factor in doing validation on the full object with every call, autosave has the potential to become an expensive operation. Moving autosave operations to GraphQL mutations will help us solve this problem outside the constraints of a traditional REST API design and more closely represent the types of actions our users are taking.

As we move all our internal infrastructure to GraphQL, our ultimate goal is to expose a GraphQL interface to our customers, along with an explorer that will make it so consumers can interact with our schema right from the browser.

If you’re interested in working with GraphQL, we’re hiring engineers at Courier. You can check out our open roles here – we hope to hear from you!