Throw in the serious performance that AppSync can achieve, along with the tight integration with other AWS Services (for example, decorator-based resolving of certain schema keys based on the users Cognito groups) and it's clear AppSync is a huge step forward for developing and evolving web & app APIs.

The Introspection Endpoint

All GraphQL APIs have an introspection endpoint. This is an endpoint that allows queries on the metadata of the schema for that particular GraphQL API. AppSync exposes this endpoint by default.

From the Apollo blog:

We believe that introspection should primarily be used as a discovery and diagnostic tool when we’re in the development phase of building out GraphQL APIs. While we don’t often use introspection directly, it’s important for tooling and GraphQL IDEs like Apollo Studio, GraphiQL, and Postman. Behind the scenes, GraphQL IDEs use introspection queries to power the clean user experience helpful for testing and diagnosing your graph during development.

In a recent penetration test for a client, it surfaced that our introspection endpoint was queryable. I would go ahead and assume most penetration testers would raise this as an issue, as ultimately this API is a single place that does expose the entire surface area of your GraphQL API, which could aid bad actors in constructing a more advanced multi-faceted attack. Without this endpoint, attackers would have to laboriously move through your front-end apps and monitor network traffic, and it would be more difficult to construct the entire picture of your GraphQL API.

So it makes sense to only leave this introspection endpoint available in your development environments, and somehow turn it off in your production environment (and any other public environments). This is also the general guidance from the Apollo developer team.

Luckily one of the many AWS services that integrates well with AppSync is Web Application Firewall or "WAF". With only a little more CDK code over and above the provisioning of our API, we can construct firewall rules that will block queries to the introspection endpoint.

Let's first provision our basic AppSync API:

const api = new appsync.GraphqlApi(this, "Api", {
      name: "UnintrospectableAppSyncApi",
      schema: appsync.SchemaFile.fromAsset(
        path.join(__dirname, "schema.graphql")
      ),
      authorizationConfig: {
        defaultAuthorization: {
          authorizationType: appsync.AuthorizationType.API_KEY,
        },
      },
    });

    new CfnOutput(this, "GraphQLAPIURL", {
      value: api.graphqlUrl,
    });

And with a simple cdk deploy we are up and running.

 ✅  AppsyncIntrospectionWafStack 

✨  Deployment time: 37.23s

Outputs:
AppsyncIntrospectionWafStack.GraphQLAPIURL = https://i33yq5nw3fgkxixzek3ixynz4u.appsync-api.us-east-1.amazonaws.com/graphql
Stack ARN:
arn:aws:cloudformation:us-east-1:XXX:stack/AppsyncIntrospectionWafStack/a4704550-c76c-11ed-80ea-0a701dd151a5

Now it is worth noting that your AppSync API Introspection endpoint is under the same authentication as the rest of your API. In this case, we're using an API key for simplicity. That is of course some protection, but if you have a public API or your API callers need a Cognito account, but anybody can sign up for your app, then it is still very easy for nefarious actors to get access to your introspection endpoint contents.

With our API up we can now query the introspection endpoint:

curl --location --request POST 'https://i33yq5nw3fgkxixzek3ixynz4u.appsync-api.us-east-1.amazonaws.com/graphql' \
--header 'x-api-key: da2-coib25utiffj3gzioeskpkl3ka' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query MyQuery {\n  __schema {\n    types {\n      name\n    }\n  }\n}","variables":{}}'

Note the __schema token in the body of the request.

And in return we see our entire GraphQL schema:

{"data":{"__schema":{"types":[{"name":"Query"},{"name":"Blog"},{"name":"ID"},{"name":"String"},{"name":"BlogInput"},{"name":"__Schema"},{"name":"__Type"},{"name":"__TypeKind"},{"name":"__Field"},{"name":"__InputValue"},{"name":"Boolean"},{"name":"__EnumValue"},{"name":"__Directive"},{"name":"__DirectiveLocation"}]}}}

Now let's provision our WAF layer to hide the introspection endpoint.

const firewall = new waf.CfnWebACL(this, "waf-firewall", {
      defaultAction: {
        allow: {},
      },
      description: "Block GraphQL introspection queries",
      scope: "REGIONAL",
      visibilityConfig: {
        cloudWatchMetricsEnabled: true,
        metricName: "BlockIntrospectionMetric",
        sampledRequestsEnabled: true,
      },
      rules: [
        {
          name: "BlockIntrospectionQueries",
          priority: 0,
          action: {
            block: {},
          },
          visibilityConfig: {
            sampledRequestsEnabled: true,
            cloudWatchMetricsEnabled: true,
            metricName: "BlockedIntrospection",
          },
          statement: {
            byteMatchStatement: {
              fieldToMatch: {
                body: {},
              },
              positionalConstraint: "CONTAINS",
              searchString: "__schema",
              textTransformations: [
                {
                  type: "LOWERCASE",
                  priority: 0,
                },
              ],
            },
          },
        },
      ],
    });

    new CfnWebACLAssociation(this, "web-acl-association", {
      webAclArn: firewall.attrArn,
      resourceArn: api.arn,
    });

Fairly straightforward stuff. We provision an instance of CfnWebACL with the relevant config, and then an instance of CfnWebACLAssociation to associate that Firewall with our AppSync API.

Note though that we lowercase the "__schema" string, as the matching is case-sensitive. See this unrelated but interesting AppSync vulnerability discovered by the DataDog Security team as a reminder of what can happen when you don't take casing into account!

With another cdk deploy we have our firewall up and running.

Now when we try the same curl command above, we get a 403 Forbidden error.

curl --location --request POST 'https://i33yq5nw3fgkxixzek3ixynz4u.appsync-api.us-east-1.amazonaws.com/graphql' \
--header 'x-api-key: da2-coib25utiffj3gzioeskpkl3ka' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query MyQuery {\n  __schema {\n    types {\n      name\n    }\n  }\n}","variables":{}}'

{
  "errors" : [ {
    "errorType" : "WAFForbiddenException",
    "message" : "403 Forbidden"
  } ]
}

And that's it! One less tool at the attacker's disposal. And one less thing for your penetration testers to eagerly point out. 😎

As always, the full code is available on Github.

I have a client that uses mParticle's customer data platform (CDP) to ingest analytics events from various sources including a mobile app, a web app and a cloud-based backend, as well as events from 3rd party systems like Branch (mobile app install attribution) or Algolia (search item click conversion).

You can use mParticle to set up connections to downstream 3rd party systems which would then receive all the ingested analytics events in near real-time. For example, you could forward events to Mixpanel for in-depth user/feature analysis, or Intercom to then be able to message users based on their in-app activity.

In the world of mParticle, analytics events are broken down into categories like screen navigation events, e-commerce/commercial events, or "custom" events that are more specific to your domain. mParticle supports forwarding most event types to most providers, but some support is still lacking.

The client recently integrated Iterable as a customer engagement solution, but unfortunately, Iterable only supports receiving custom events from mParticle, so screen/navigation events and "lifecycle" events like a mobile app "Session Start" event, were missing after the mParticle/Iterable connection was configured.

The marketing team very much expressed interest in being able to target users for certain messaging, based on their session behaviour and screen journeys.

We realized that we would need a custom solution to effectively ship analytics events from mParticle to Iterable that weren't catered for automatically by the configured connection.

Our first thought was to use a webhook API from mParticle, with a lambda invocation to forward the event batch to Iterable using the Iterable API. However, given the marketing team's requirements, the data flow didn't need to be real-time. Something like once per hour was likely good enough. In addition, the webhook API didn't need any kind of sophisticated response, but rather it was just "delivering" an analytics event batch with a relatively well-understood schema. Finally, we knew that the API would be called very frequently as events streamed in, and this number would increase as the user activity on the platform scaled up.

The Storage-First Pattern

Using the Storage First pattern you can capture the payload of incoming web requests and save them straight to SQS, SNS, EventBridge, Kinesis or a host of other AWS Services. This is viable when you don't need a lambda to perform more complex authentication/authorization, parsing, transformation and/or saving of the payload. Using the pattern in the correct circumstances allows you to reduce the latency of the response (no lambda cold start or processing time), lower cost (no lambda invocations), and also facilitates the ease-of-retry that you get with lambdas with an async event source should any processing fail.

Our need to batch up incoming analytics events and send them on to another 3rd party fits this use case. We can use a API Gateway SQS service integration, store the event batches in an SQS queue, and use a lambda on a cron job EventBridge recurring schedule 😎 to invoke the lambda. It would consume all stored messages and call the Iterable trackBulk API. We did observe that event payloads from mParticle were typically in the 5-10KB range so well within the 256KB SQS message size limit. This configuration would also avoid the long-polling of the queue by the lambda, which greatly increases the number of requests to the queue (remember SQS is billed by the number of requests). This configuration would result in only a handful of SQS requests every hour (the number of event batches/messages in the queue divided by 10 messages per batch) and so would be very cost-effective indeed!

So, once more unto the breach!

First, we provision our queue.

// New SQS queue
    const sqsQueue = new sqs.Queue(this, `${id}-events-queue`, {
      queueName: `${id}-queue`,
      visibilityTimeout: Duration.seconds(30),
      retentionPeriod: Duration.days(4),
      receiveMessageWaitTime: Duration.seconds(0),
      deadLetterQueue: {
        queue: new sqs.Queue(this, `${id}-events-dlq`),
        maxReceiveCount: 3,
      },
    });

• The visibilityTimeout should be the same timeout duration that we set for our consuming lambda. Here we've gone for 30 seconds, which should be plenty of time to process an hour's worth of analytics events at current scale. We'd need to keep an eye on the average duration of the lambda as our analytics traffic scales.

• The retentionPeriod is set at 4 days (which is the default) and should be plenty of time to triage the lambda should it stop working, while not losing any analytics events.

• The receiveMessageWaitTime parameter defaults to 0, so no actual need to set it here, but noting here as this disables any wait time or long-polling on any ReceiveMessage calls, reducing our "SQS requests" billable amount.

• We provision a simple dead-letter queue. This would allow us to manually retry the processing of events at a later time, should we need to (for example, if the Iterable API went down for a prolonged period).

Now, our Gateway API, Rest resource and some related IAM privileges.

// Rest API
    const restApi = new apigw.RestApi(this, `${id}-gateway`, {
      restApiName: `${id}-gateway`,
      description: "API Gateway for mParticle Iterable API Proxy",
      deployOptions: {
        stageName: "dev",
      },
    });

// You likely want to add an authentication mechanism of some sort to your API
    // You can usually configure your 3rd party to use this API key in the webhook configuration
    restApi.addApiKey("APIKey", {
      apiKeyName: "APIKey",
      value: "2526a244-5766-4eca-aced-65643b080867",
    });

    // Event batch Rest API resource
    const eventBatchResource = restApi.root.addResource("event-batch");

    // Yes it's IAM again :-)
    const gatewayServiceRole = new iam.Role(this, "api-gateway-role", {
      assumedBy: new iam.ServicePrincipal("apigateway.amazonaws.com"),
    });

    // This allows API Gateway to send our event body to our specific queue
    gatewayServiceRole.addToPolicy(
      new iam.PolicyStatement({
        resources: [sqsQueue.queueArn],
        actions: ["sqs:SendMessage"],
      })
    );

Ok, now that we have our Rest resource provisioned at /event-batch , let's add our SQS proxy integration.

// A request template that tells API Gateway what action (SendMessage) to apply to what part of the payload (Body)
    const requestTemplate =
      'Action=SendMessage&MessageBody=$util.urlEncode("$input.body")';

    const AWS_ACCOUNT_ID = "YOUR_AWS_ACCOUNT_ID";
    const awsIntegrationProps: apigw.AwsIntegrationProps = {
      service: "sqs",
      integrationHttpMethod: "POST",
      // Path is where we specify the sqs queue to send to
      path: `${AWS_ACCOUNT_ID}/${sqsQueue.queueName}`,
      options: {
        passthroughBehavior: apigw.PassthroughBehavior.NEVER,
        credentialsRole: gatewayServiceRole,
        requestParameters: {
        // API Gateway needs to send messages to SQS using content type form-urlencoded
          "integration.request.header.Content-Type": 'application/x-www-form-urlencoded',
        },
        requestTemplates: {
          "application/json": requestTemplate,
        },
        integrationResponses: [
          {
            statusCode: "200",
          },
          {
            statusCode: "500",
            responseTemplates: {
              "text/html": "Error",
            },
            selectionPattern: "500",
          },
        ],
      },
    };

// Add the Rest API Method, along with the integration, 
// Also creating the required 200 Method Response 
eventBatchResource.addMethod("POST", new apigw.AwsIntegration(awsIntegrationProps),
{ methodResponses: [{ statusCode: "200" }] });

Ok great! Now with a simple cdk deploy we have our Gateway API, our Rest API & SQS service integration, and our SQS queue itself. A simple test with curl:

curl --location --request POST 'https://{YOUR_API_ID}.execute-api.us-east-1.amazonaws.com/dev/event-batch' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: 2526a244-5766-4eca-aced-65643b080867' \
--data-raw '{ "testEventData": "test" }'

And we should be able to see our message in the queue:

We then configured an mParticle connection to our webhook API, and started receiving our analytics event batches. All that was left was to provision our event forwarder lambda, and associated EventBridge recurring rule to invoke it.

// event forwarder lambda
    const forwarder = new NodejsFunction(this, `${id}-event-forwarder`, {
      runtime: Runtime.NODEJS_16_X,
      functionName: `${id}-event-forwarder`,
      entry: "src/functions/forwarder/forwarder.ts",
      handler: "handler",
      memorySize: 512,
      timeout: Duration.seconds(30),
      architecture: Architecture.ARM_64,
      environment: {
        SQS_QUEUE_URL: sqsQueue.queueUrl,
      },
      initialPolicy: [
        new PolicyStatement({
          actions: ["sqs:ReceiveMessage", "sqs:DeleteMessageBatch"],
          resources: [sqsQueue.queueArn],
        }),
      ],
    });

    const lambdaTarget = new targets.LambdaFunction(forwarder);
    new events.Rule(this, "ForwarderScheduleRule", {
      description: "Forward all stored mParticle events to Iterable every hour",
      schedule: events.Schedule.rate(Duration.hours(1)),
      targets: [lambdaTarget],
      // omitting the `eventBus` property puts the rule on the default event bus
    });

And now the lambda itself:

import { EventBridgeEvent } from "aws-lambda";
import { ReceiveMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
import axios from "axios";

type ScheduledEvent = {};

const sqsClient = new SQSClient({ region: "us-east-1" });
const iterableClient = axios.create({
  baseURL: "https://api.iterable.com/api",
  headers: {
    "Api-Key": "YOUR_ITERABLE_API_KEY",
    "Content-Type": "application/json",
  },
});

export const handler = async (_event: EventBridgeEvent<ScheduledEvent>) => {
  const receiveMessageCommand = new ReceiveMessageCommand({
    QueueUrl: process.env.SQS_QUEUE_URL,
    MaxNumberOfMessages: 10,
    WaitTimeSeconds: 0,
  });

  let sqsResponse = await sqsClient.send(receiveMessageCommand);
  while (sqsResponse.Messages && sqsResponse.Messages?.length > 0) {
    const iterablePayload = mapEventsToIterablePayload(sqsResponse.Messages);

    // https://api.iterable.com/api/docs#events_trackBulk
    await iterableClient.post("/events/trackBulk", iterablePayload);

    const deleteMessageBatchCommand = new DeleteMessageBatchCommand({
      QueueUrl: process.env.SQS_QUEUE_URL,
      Entries: sqsResponse.Messages.map((message) => ({
        Id: message.MessageId,
        ReceiptHandle: message.ReceiptHandle,
      })),
    });
    await sqsClient.send(deleteMessageBatchCommand);

    sqsResponse = await sqsClient.send(receiveMessageCommand);
  }
};

• We set the MaxNumberOfMessages to 10, which is the max, to maximize throughput of the lambda and minimize the number of `ReceiveMessage` calls we'll need to make.

• The WaitTimeSeconds is arguably duplicative of our cdk queue's receiveMessageWaitTime as it performs the same function, but from the SDK's side. Take your pick!

• The mapEventsToIterablePayload is unimplemented here but this is of course very domain specific. The output of that function is a json object in a schema that is accepted by the Iterable API.

• Once we get a successful response from Iterable, we batch delete those now-processed messages from the queue, and then read the next batch.

Once all up and running we saw our analytics events arrive in Iterable over the course of the day, with minimal Lambda & SQS costs.

What about idempotency or partial failure?

Great question, as well-behaving lambdas should take this into account. In this case, we get a free pass as all the analytics events have a messageId. If Iterable receives multiple events with the same ID, it does not create a new event but rather overwrites the existing event. As events are effectively immutable, this is a safe operation. So if some of our messages were to be reprocessed, it wouldn't be the end of the world.

Thanks for reading! See also

Full code for this solution is on Github:

https://github.com/markgibaud/mparticle-iterable-api-proxy-sqs-integration

Jeremy Daly introduces the Storage-First pattern way back in this 2020 blog post:

https://www.jeremydaly.com/the-storage-first-pattern/

More recently, Robert Bulmer deploys a similar pattern but using S3:

https://awstip.com/storage-first-pattern-in-aws-with-api-gateway-part-1-using-s3-216e20b08353

Also check out the AWS Solutions Construct CDK template for a much more fully-baked solution:

https://docs.aws.amazon.com/solutions/latest/constructs/aws-apigateway-sqs.html

So we were delighted when the Amazon EventBridge scheduler was announced in the lead-up to ReInvent 2022! The scheduler is perfect for this use case using a once-off (rather than recurring) schedule and is very simple to implement.

To remind folks, AWS EventBridge is a serverless event bus that makes it easy to connect up applications using data from your apps, integrated SaaS applications, and other AWS services running as part of your platform.

Recently added is the EventBridge Scheduler, and standalone component which allows you to schedule events to trigger at specific times or intervals, resulting in a new event put into the event bus.

The implementation

In our sports club mobile app, you can access a menu to do several things to a booking, for example, send an email with details of your court booking, or add the event to your calendar. We added a new menu item "Set Reminder" and gave the user the option to receive the notification 1, 6 or 24 hours before their match.

The process to create the reminder is quite simple:

1. The app would POST to a create reminder Rest API (AWS API Gateway endpoint). Included in the payload would be the message, the reminder time and the push notification device token for the mobile device.

2. That would invoke a create-reminder lambda which would create a one-time schedule in AWS EventBridge Scheduler. The target would be another lambda function, send-reminder.

3. At the specified time, the send-reminder lambda invokes from the event and in our case, calls out to Firebase to send out our reminder push notification.

Let's get started! First, we need the infrastructure. Here is the CDK code to set up the Rest API, 2 lambda functions and EventBridge event bus, along with associated policies.

import * as cdk from "aws-cdk-lib";
import { Duration } from "aws-cdk-lib";
import * as apigw from "aws-cdk-lib/aws-apigateway";
import { Rule } from "aws-cdk-lib/aws-events";
import { LambdaFunction } from "aws-cdk-lib/aws-events-targets";
import {
  Effect,
  Policy,
  PolicyStatement,
  Role,
  ServicePrincipal,
} from "aws-cdk-lib/aws-iam";
import { Architecture, Runtime } from "aws-cdk-lib/aws-lambda";
import { NodejsFunction } from "aws-cdk-lib/aws-lambda-nodejs";
import { Construct } from "constructs";

export class EventBridgeRemindersStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Core infra: EventBridgeReminders Rest API
    const eventBridgeRemindersApi = new apigw.RestApi(this, `${id}-gateway`, {
      restApiName: `${id}-gateway`,
      description: "API for creating push notification reminders",
      deployOptions: {
        stageName: "dev",
      },
    });

    // Core infra: Eventbridge event bus
    const eventBus = new cdk.aws_events.EventBus(this, `${id}-event-bus`, {
      eventBusName: `${id}-event-bus`,
    });

    // need to create a service-linked role and policy for 
    // the scheduler to be able to put events onto our bus
    const schedulerRole = new Role(this, `${id}-scheduler-role`, {
      assumedBy: new ServicePrincipal("scheduler.amazonaws.com"),
    });

    new Policy(this, `${id}-schedule-policy`, {
      policyName: "ScheduleToPutEvents",
      roles: [schedulerRole],
      statements: [
        new PolicyStatement({
          effect: Effect.ALLOW,
          actions: ["events:PutEvents"],
          resources: [eventBus.eventBusArn],
        }),
      ],
    });

    // Create reminder lambda
    const createNotificationReminderLambda = new NodejsFunction(
      this,
      "createNotificationReminder",
      {
        runtime: Runtime.NODEJS_16_X,
        functionName: `${id}-create-notification-reminder`,
        entry: "src/functions/notificationReminder/create.ts",
        handler: "handler",
        memorySize: 512,
        timeout: Duration.seconds(3),
        architecture: Architecture.ARM_64,
        environment: {
          SCHEDULE_ROLE_ARN: schedulerRole.roleArn,
          EVENTBUS_ARN: eventBus.eventBusArn,
        },
        initialPolicy: [
          // Give lambda permission to create the group & schedule and pass IAM role to the scheduler
          new PolicyStatement({
            actions: [
              "scheduler:CreateSchedule",
              "scheduler:CreateScheduleGroup",
              "iam:PassRole",
            ],
            resources: ["*"],
          }),
        ],
      }
    );

    const sendNotificationLambda = new NodejsFunction(
      this,
      "sendNotification",
      {
        functionName: `${id}-send-notification`,
        runtime: Runtime.NODEJS_16_X,
        architecture: Architecture.ARM_64,
        handler: "handler",
        entry: "src/functions/notification/send.ts",
        memorySize: 512,
        timeout: Duration.seconds(3),
        bundling: {
          commandHooks: {
            beforeBundling(): string[] {
              return [];
            },
            // This is an easy way to include files in the bundle
            // of your lambda. A more secure method would be to
            // retrieve and cache this file from S3 in the lambda code
            afterBundling(inputDir: string, outputDir: string): string[] {
              return [
                `cp ${inputDir}/src/functions/notification/firebaseapp-config-XXXXXXX.json ${outputDir}`,
              ];
            },
            beforeInstall() {
              return [];
            },
          },
        },
      }
    );

    // Rule to match schedules for users and attach our email customer lambda.
    new Rule(this, "ReminderNotification", {
      description: "Send a push notification reminding user of a booked court",
      eventPattern: {
        source: ["scheduler.notifications"],
        detailType: ["ReminderNotification"],
      },
      eventBus,
    }).addTarget(new LambdaFunction(sendNotificationLambda));

    const notificationReminderRestResource =
      eventBridgeRemindersApi.root.addResource("notification-reminder");
    notificationReminderRestResource.addMethod(
      "POST",
      new apigw.LambdaIntegration(createNotificationReminderLambda)
    );

    // CDK Outputs
    new cdk.CfnOutput(this, "eventBridgeRemindersApiEndpoint", {
      value: eventBridgeRemindersApi.url,
    });
  }
}

Some notes on this code

• Take note of the various IAM privileges we need to apply to the various components to make this all work. IAM is always fun!

• As noted in the comments, we're using the esbuild's commandHooks functionality to bundle our Firebase config file. This is just for convenience, but you may want to avoid having to commit a file of secrets like that into source control, and rather have the lambda fetch that file from a secured "secrets" S3 bucket.

• The EventBridge scheduler is currently only available in the "major" AWS regions, so while a cdk deploy on this code would work in say eu-west-2, when the create-reminder lambda invokes, you would get an "Endpoint not found" error because there is no EventBridge Scheduler endpoint yet in the London region! Check supported regions here.

• And of course, you'd likely want some authentication on that Rest API!

Before we have a look at our lambda code, let's have a quick look at the incoming payload we are expecting:

{
      device_token: token,
      datetime: reminderDate.format('YYYY-MM-DDThh:mm:ss'), //eg. '2023-01-23T20:30:00'
      message: `Your club match starts in ${hours} ${
        hours === 1 ? 'hour' : 'hours'
      }`
    }

• We leave it up to the app to specify the reminder message text.

• The date here is UTC but the Scheduler also supports specifying timezones.

Now let's have a look at the create-reminder lambda code.

import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
import {
  SchedulerClient,
  CreateScheduleCommand,
  FlexibleTimeWindowMode,
  CreateScheduleGroupCommand,
} from "@aws-sdk/client-scheduler";
import { v4 as uuidv4 } from "uuid";
import { z } from "zod";

const schedulerClient = new SchedulerClient({ region: "eu-west-1" });

const requestSchema = z.object({
  device_token: z.string(),
  datetime: z.string(),
  message: z.string(),
});
type NotificationReminder = z.infer<typeof requestSchema>;

export const handler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  if (!event.body) {
    return {
      statusCode: 400,
      body: JSON.stringify({ message: "No body found" }),
    };
  }

  const reminder: NotificationReminder = requestSchema.parse(
    JSON.parse(event.body)
  );

  try {
    // Create a schedule group
    // You could argue this should be part of the infra (cdk)
    // I would agree but a CDK construct for a ScheduleGroup
    // is not yet available
    await schedulerClient.send(
      new CreateScheduleGroupCommand({
        Name: "NotificationRulesScheduleGroup",
      })
    );
  } catch (error) {
    // the above would throw if that ScheduleGroup already exists
}

  try {
    const cmd = new CreateScheduleCommand({
      // A rule can't have the same name as another rule
      // in the same Region and on the same event bus.
      Name: `${uuidv4()}`,
      GroupName: "NotificationRulesScheduleGroup",
      Target: {
        RoleArn: process.env.SCHEDULE_ROLE_ARN,
        Arn: process.env.EVENTBUS_ARN,
        EventBridgeParameters: {
          DetailType: "ReminderNotification",
          Source: "scheduler.notifications", 
        },
        Input: JSON.stringify({ ...reminder }),
      },
      FlexibleTimeWindow: {
        Mode: FlexibleTimeWindowMode.OFF,
      },
      Description: `Send push notification to ${reminder.device_token} at ${reminder.datetime}`,
      ScheduleExpression: `at(${reminder.datetime})`,
    });
    await schedulerClient.send(cmd);
  } catch (error) {
    console.log("failed", error);
  }

  return {
    statusCode: 200,
    body: JSON.stringify({
      message: "Notification reminder created successfully",
    }),
  };
};

Some notes

• We use the excellent zod library which is a great way to get from a json payload to a Typescript type via explicitly validating against a predefined schema.

• The lambda creating the Schedule Group is a temporary workaround for this not yet being available in CDK, as Schedule Group makes more sense as an infrastructure concern IMO.

• We set the FlexibleTimeWindow to OFF as we want the target lambda to invoke immediately. In practice, I notice this is usually within 30 seconds, but can be up to 50 seconds. Setting the window to FLEXIBLE can make sense when you deliberately might want jitter in your invocations, for example restarting a fleet of EC2 instances but not wanting them all to restart at the same time!

Now let's look at the send-notification lambda code:

import { EventBridgeEvent } from "aws-lambda";
import { NotificationReminder } from "../notificationReminder/create";
import * as fbAdmin from "firebase-admin";

export const handler = async (
  event: EventBridgeEvent<"ReminderNotification", NotificationReminder>
) => {
  if (!fbAdmin.apps.length) {
    process.env.GOOGLE_APPLICATION_CREDENTIALS =
      "./firebaseapp-config-XXXXXXX.json";
    fbAdmin.initializeApp({ credential: fbAdmin.credential.applicationDefault() });
  }

  const result = await fbAdmin
    .messaging()
    .sendToDevice(event.detail.device_token, {
      notification: {
        title: `Court Reminder`,
        body: event.detail.message,
        sound: "default",
      },
    });

  console.log("result", JSON.stringify(result));
};

Not much to explain here - we're just using the Firebase Admin SDK to send the push notification itself, using the data from the EventBridge event.

And voila! We receive our notification. It's game time 😎

Full source code is available on GitHub.

And Finally

Thanks to David Boyne and the ServerlessLand folks for the inspiration. Check out ServerlessLand for other great event-based patterns and specifically this one that inspired this feature & post!