Introducing Scheduled Triggers: API Driven Cron Jobs and Scheduled Events

We are happy to announce the stable release of v1.3 which brings a slew of features like Data Federation via Remote Joins, Support for Relay and Scheduled Triggers.

Scheduled Triggers are used to execute custom business logic, via webhooks, at specific points in time. It extends the idea of Event Triggers (which are driven by table events) to a flexible API that can be used to schedule events at some time(s) for any payload and webhook.

Scheduled Triggers are a great fit with serverless because each event can be mapped to an individual function which can scale infinitely with no-ops!

Scheduled Triggers comes with two types of scheduling: Cron Triggers - used to execute periodic events according to a cron schedule and One-off Scheduled Events - used for one-time execution, typically created inside some business logic.

API driven scheduling

Scheduled Triggers can be created from both the console and through metadata APIs. You may use the console to create a Cron Trigger which has a fixed payload on a static schedule. You may also use the console to create any adhoc one-off scheduled events.

But suppose your event payload is dynamic (say depending on the user), then you can also schedule an event via the metadata API. This metadata API would typically be called from inside your application code. The simplest API call to schedule a one-off scheduled event will look like:

{
  "type": "create_scheduled_event",
  "args": {
    "webhook": "https://my-awesome-serverless-fn.com/send-email",
    "schedule_at": "2022-07-20T12:45:00Z",
    "payload": {
      "email": "[email protected]"
    }
  }
}

API for creating a scheduled event

You can also create cron triggers dynamically via metadata API, e.g. when you want to perform periodic actions for each user.

How does it work?

When you create a scheduled trigger, with a cron schedule or timestamp, Hasura will create event(s) in the database with a timestamp associated with it. There is a worker thread running in the background which fetches events at the appropriate time that need to be delivered. There is another thread which generates future events for Cron triggers. The event delivery mechanism is similar to Event Triggers i.e. atleast-once guaranteed. Hasura also stores the full logs of every invocation for later retrieval.

Fault Tolerance

If Hasura is down, newer events won't be generated (for Cron triggers) or existing events wouldn't be processed temporarily. But what happens when the server is back up and running? In this case, Hasura will rehydrate the events and existing events that were scheduled to run will be (re)triggered based on a customisable tolerance configuration.

For example: If an event was scheduled for 12am and Hasura went down at 11:59pm and came back up at 12:01am, depending on the tolerance config (default: 6 hours), Hasura will attempt to deliver these existing events.

Hasura also gives a flexible retry configuration to retry the event in case of HTTP failures. This includes number of retries and interval between each retry (to avoid overloading your webhook).

Metadata workflow

Cron triggers will usually be part of your Hasura metadata as it's configuration will typically be fixed. This will ensure that it can be migrated between different environments (like staging, production). If your cron trigger is dynamic (say contains user info in payload), then you can skip including it in metadata as well.

One-off scheduled events will typically be API-driven and can be archived once the event is delivered. Hence, it doesn't need to be part of your metadata workflow and can remain local to the environment where it is created.

Actions & Scheduled Triggers

Scheduled triggers goes well with Hasura Actions as you would typically create a scheduled event as part of a mutation with custom business logic. Let's take the example of scheduling a tweet: You will create a custom mutation through Actions and define the logic to validate and insert the tweet into the database. Once the payload is validated, you will be calling the create_cron_trigger or create_scheduled_event for the specified timestamp and the event delivery will be taken care by Hasura.

Both Actions and Scheduled Triggers fit nicely in the serverless pattern as the source of data and logic is spread across different APIs. Of course you are not limited to serverless runtimes, since all Hasura needs is a valid HTTP POST endpoint.