Serverless logo
Products
FRAMEWORK
Overview
CI/CD
Secrets
Plugins
Pricing
Signup
CONSOLE
Overview
Pricing
Signup
CLOUD
Overview
Pricing
FAQ
Signup
Company
ABOUT US
About
Careers
Contact Us
SUPPORT
Get Support
COMMUNITY
Slack
Forum
Partners
Meetups
LEARN
Blog
Examples
Guides
Serverless Cloud logoDocsPricingFAQ
Serverless Cloud Dashboard
Serverless Cloud logo
Serverless Cloud Dashboard
DocumentationPricingFAQ
Serverless logo
Serverless Cloud - Docs

Serverless Cloud – Documentation

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

Item title

Item description

X
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

Item title

Item description

Serverless logo
Product
Expand
Option 1Option 2Option 3
DocsPricing
Company
Expand

Feature 1

Lorem ipsum dolor emet sin dor lorem ipsum

Feature 2

Lorem ipsum dolor emet sin dor lorem ipsum

Feature 3

Lorem ipsum dolor emet sin dor lorem ipsum

Feature 4

Lorem ipsum dolor emet sin dor lorem ipsum
Search
Sales & Support
LoginSign Up
Open MenuClose Menu
Login / Sign Up
Go to GitHub
Serverless Cloud - Build full stack apps better and faster than everyone else | Product Hunt
Home
How it Works
Development Workflows
Building Applications
Link 1Link 1Link 1
Building Applications
Link 1Link 1Link 1
Building Applications
Link 1Link 1Link 1
Automated Testing
CLI Reference

Serverless Events

Serverless Cloud supports publishing and handling events so you can easily build event-driven applications.

Events let you do work "in the background" and allow you to decouple your application to make it more scalable and resilient to errors. Events can also be published "in the future" if you need to do the work at a later time.

For example, instead of sending a welcome email to a new user immediately in an api.post() handler, you can send a "user joined" event and send the email from the event handler. This makes your API much more responsive and means your API will not fail if the email server is not available.

One advantage of event-driven applications is that they are much easier to extend. For example if you decide that you want to add billing to your application, you can write another handler that adds the user to the billing system.

Publishing events with events.publish()

To publish an event you use the events.publish() method, and provide a name and a "body" that contains application-specific data to send in the event.

For example, this will publish a "user.joined" event:

const { api, events } = require("@serverless/cloud");

await events.publish("user.joined", {
  user_id: "2b6mgh78g334",
  email: "newuser@example.com"
})

You can delay when an event is published using the "after" option. For example, this will send the "user.joined" event in one day:

await events.publish("user.joined", { after: "1 day" }, {
  user_id: "2b6mgh78g334",
  email: "newuser@example.com"
})

after must be greater than zero, and can be up to one year in the future. It can be expressed in any of these formats:

  • a number of milliseconds to wait before sending the event
  • a unix epoch timestamp in milliseconds, such as the output from Date.getTime()
  • a string containing a date and time in UTC format, such as "2022-01-14T17:46:05.811Z"
  • a Javascript Date object containing the date and time when the event should be sent. You can use dayjs for complex data calculations.
  • a string in the format "<number> <units>", such as "1 day". Units can be seconds, minutes, hours, days, weeks, months, or years, and can be either singular or plural, so "1 day" and "1 days" are equivalent. Calculations are done in UTC. If you need to take daylight savings into account, you'll need to calculate the date yourself and provide it as a string in UTC format.

The body you send in the event can be any data type that can be JSON stringified. The event, including its body and metadata must be less than 256KB.

Handling events with events.on()

To handle an event you use the events.on() method, and provide the event name and a handler function.

For example, this will call the handler when a "user.joined" event is received.

events.on("user.joined", async ({ body }) => {
   // send a welcome email using body.email
})

The handler receives an object with these properties:

  • id: the event identifier string
  • name: the event name, such as "user.joined" in the example above
  • body: the body that was provided to events.publish()
  • time: the timestamp when events.publish() was called, as epoch time in milliseconds
  • delay: the amount of time the event was delayed, in milliseconds

There can be more than one handler for a given event name. To add another handler just call events.on() again with the same event name. Your handlers will be called in the order they are defined in your code. It's also ok if there are no handlers for an event, the event will just be ignored.

Internally, events are placed in a queue and processed as fast as possible. The actual time an event is processed will be on or after the "after" parameter provided to the .publish() call, and depends on how much load your application is receiving. You can't rely on the event being processed at an exact time or within a given time window.

There is no guarantee that events will be processed in order, and no guarantee that your handler will only get called once for each event, so your application needs to handle out-of-order events and duplicate events.

If any of your handlers throw an error, processing is considered to have failed. Failed events are retried every six minutes, for up to 14 days, after which the event is dropped.

Reacting changes in Serverless Data

Serverless Cloud allows you to build event-driven workflows by dispatching the change events using data.on() from data interface of the SDK. This allows you to decouple your API endpoints from the business logic that can be run asynchronously. See here for more detailed information on how to build event-driven apps based on Serverless Data.

Reacting changes in Serverless Storage

Serverless Storage emits events when a new file is added or updated for a stage. Developers can register events for such changes in storage using storage.on() function from storage interface of SDK. This is particularly useful when it's required to make async changes without blocking the API that helps user upload files. See here for more information.

Edit this page
Serverless logo
Product
Expand
Option 1Option 2Option 3
DocsPricing
Company
Expand

Feature 1

Lorem ipsum dolor emet sin dor lorem ipsum

Feature 2

Lorem ipsum dolor emet sin dor lorem ipsum

Feature 3

Lorem ipsum dolor emet sin dor lorem ipsum

Feature 4

Lorem ipsum dolor emet sin dor lorem ipsum
Search
Sales & Support
LoginSign Up
Open MenuClose Menu
FRAMEWORK
Overview
CI/CD
Secrets
Plugins
Pricing
CONSOLE
Overview
Pricing
Signup
RESOURCES
Framework DocsConsole DocsGuidesExamplesBlog
COMMUNITY
SlackMeetupsForum
SUPPORT
Contact UsPremium Support
COMPANY
AboutCareersPartners
Join our monthly newsletter
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
© 2022 Serverless, Inc. All rights reserved.
Terms of ServicePrivacy Policy