Run cloud functions in the background

Subscribe a Lambda function to an SNS Topic and then asynchronously publish JSON payloads to it. SNS is a publish-subscribe (pub/sub) system. Messages are immediately pushed to subscribers when they are sent by publishers.

🚜 Work Locally

Events are defined in .arc under @events:



Event names are lowercase alphanumeric and can contain dashes. It is recommended to create a naming convention to group similar events and (ideally) keep them single purpose.

Event Subscribers

Running arc init with the .arc file above will generate the following local source code:

  • /src/events/account-signup
  • /src/events/account-check-email

These are event handlers subscribed to the event name defined in .arc.

Events are supported by arc sandbox

🌾 Provision

Running arc deploy will setup the following AWS resources:

  • AWS::Lambda::Function
  • AWS::SNS::Topic
  • AWS::Lambda::Permission

Additionally AWS::SSM::Parameter resources are created for every SNS Topic which can be inspected at runtime:

  • /[StackName]/events/[EventName] with a value of the generated SNS Topic ARN

All runtime functions have the environment variable AWS_CLOUDFORMATION which is the currently deployed CloudFormation stack name; this combined w the runtime aws-sdk or @architect/functions can be used to lookup these values in SSM

⛵️ Deploy

  • arc deploy to deploy with CloudFormation to staging
  • arc deploy dirty to overwrite deployed staging lambda functions
  • arc deploy production to run a full CloudFormation production deployment

💌 Publish

All runtime Lambda functions share an IAM Role that allows them to publish events to any SNS Topic in the currently deployed CloudFormation stack.

Publish an event payload to an SNS Topic


let arc = require('@architect/functions')

exports.handler = async function http(req) {
  let name = 'account-signup'
  let payload = {body: req.body}
  await{name, payload})
  return {statusCode: 201}


require 'architect-functions'

def handler
  Arc::Events.publish name: 'account-signup', payload: {ok:true}
  {statusCode: 201}



def handler(request, context):'account-signup', payload={'ok':True})
  return {'statusCode': 201}