Configure scheduled events

Scheduled events are events that you can create with the purpose of triggering certain app actions.

To configure scheduled events and enable your app to react to these events,

  1. Create scheduled events.

  2. Subscribe to a scheduled event by configuring an event listener: In manifest.json, include the events attribute within the modules.common object, specifying the scheduled-event’s name and the corresponding callback method as follows:

    "modules": {
      "common": {
        "events": {
          "<eventName>": {
            "handler": "<eventCallbackMethod>"

    On schedules, the events occur and pass a payload (data) to the listeners that have subscribed to the event. The event listener invokes the registered callback method and passes a standard payload to the method. As part of this payload, the event listener passes the data that it received from the scheduled event.

  3. Navigate to the server.js file. In the exports block, enter the callback function/method definition.

    Sample server.js
    exports = {
      onScheduledEventHandler: function(payload) {
        console.log("Logging arguments from onScheduledEvent: " + JSON.stringify(payload));
        if ( === "3") {
        //app logic

Important:Ensure that only one callback function/method is defined for an event.

Note:The default app execution timeout is 20 seconds. If the request timeout is increased to 20, 25, or 30 seconds, the app execution timeout is extended to 40 seconds.

Call to attention:

There are two payloads in play here:

Sample use case: The app can poll an external product every hour for updates and make corresponding changes in the Freshworks product.

Create scheduled events

To create one-time or recurring scheduled events, the developer platform offers the $schedule interface. As part of the app logic you can,

Create event

Use the following interface call syntax (and the SAMPLE SERVER.JS on the right pane) to create a scheduled event.

  name: "<scheduled-event-name>",
  data: {<JSON object payload passed to event listener>},
  schedule_at: "<time when the event should occur, in UTC format>",

$schedule interface call attributes

  • namestringRequired

    Unique identifier of the schedule.

  • dataobjectRequired

    Payload passed to the event listener. From the listener, this payload is again passed to the callback as part of the standard callback payload. When creating a schedule, ensure that the payload is a JSON payload and the size does not exceed 4 KB.

  • schedule_atstringRequired

    Time at which the schedule is triggered.

    For recurring events, it is the time when the event starts occurring.

  • repeatobject

    Required for recurring schedules

    Repeat pattern for recurring schedules.

Fetch details of a scheduled event

As part of the app logic, you can fetch the details of a scheduled event and decide to act on it - such as updating or deleting the schedule. Use the following interface call (and the sample SERVER.JS on the right pane) to fetch the details of a scheduled event.

$schedule.fetch({name: "<scheduled-event-name>"});

Update scheduled event

As part of the app logic, an app can modify an existing schedule. Use the following interface call syntax (and the sample SERVER.JS on the right pane) to modify a scheduled event.

$schedule.update({name: "<scheduled-event-name>", schedule_at: "<updated-value>"});

Delete scheduled event

As part of the app logic, an app can delete an existing schedule. Use the following interface call syntax (and the sample SERVER.JS on the right pane) to delete a scheduled event.

$schedule.delete({name: "<scheduled-event-name>"});

Attributes of the payload to callback

When the scheduled event occurs, the configured event listeners invoke the registered callback method and pass a standard payload.

  • currentHostobject

    Information pertaining to the Freshworks product where the app is currently deployed.

  • dataobject

    Payload that is passed to the event listener when the event occurs.

  • eventstring

    The name of the event (onScheduledEvent).

  • iparamsobject

    Installation parameters.

  • regionstring

    Region where the Freshworks product account is deployed.

    Possible values: US, EU, EUC, AUS, and IND.

  • timestampinteger

    Represents the time (epoch format) when the event was received.


  • To test a serverless app, use the latest version of Chrome.
  • As testing is only a simulation of events, actual data or record associated with the event is not created in the back-end. To create actual data and then test your event, publish your app as a custom app and test the events manually.
  • The <app's root directory>/server/test_data folder stores the test payloads used to test the events. If you modify the app manifest to add more modules and register more events, the corresponding event payloads are updated to the test_data folder, when the event is simulated as part of event testing.
  1. From the command line, navigate to the directory that contains the app related files and run the fdk run command. The FDK starts the local test server. The test URLs to access the product UI, the App Settings page (or Custom installation page), and the URL to the serverless events simulation page are displayed.

  2. Navigate to the system settings page at http://localhost:10001/system_settings. All modules configured in the App manifest are listed.

  3. In the system settings page,

    1. Select the modules for which you want to test the app logic. The Enter account URL section is displayed, with a prompt to enter the account URLs for all selected modules.
    2. In the Enter account URL section, enter valid account URL(s) for the product(s) to which the selected modules belong. During app testing, this URL plays the role of the currentHost. Based on the currentHost, the currentHost.subscribed_modules and currentHost.endpoint_urls are determined.
    3. Click Continue.
  4. If you have configured installation parameters for the app, the App Settings page is displayed at http://localhost:10001/custom_configs. Enter appropriate values for the installation parameters and click Install.

    Note:If you have not configured any installation parameters, a page is displayed with information on the configured system settings. A message stating that the app does not have an installation page is displayed.

  5. Navigate to http://localhost:10001/web/test to test the serverless events that the app uses. All modules that you select in the system settings page, for which serverless events are registered in the app manifest, are listed in the Select module drop-down.

    Note:The payloads of all serverless events that are registered in the app manifest are populated in the server/test_data folder. During the actual runtime, the payloads that are passed to the serverless event contain the currentHost attribute. In the local simulation, the payloads in server/test_data do not contain this attribute. During testing, the modules and account URLs entered in the system settings page are passed as the currentHost data.

  6. From the Select module drop-down, select Common. The Select an event drop-down is displayed and it lists all the events configured (in the app manifest) for the common module.

  7. From the Select an event drop-down, select onScheduledEvent. The payload for the event is populated on the page.

  8. Click Simulate. If the event is simulated successfully, the Simulate button’s display name changes to Success. The event payload is added to the <app's root directory>/server/test_data folder.

  9. To test more events, select another appropriate module and event and click Simulate. If the event simulation fails because of invalid payload data, the Simulate button’s display name changes to Failed. Modify the payload appropriately and click Simulate.