Periodic Triggers

Periodic Triggers allow you to set up automated HTTP requests to your endpoints on a scheduled basis using cron expressions.

Overview

Periodic Triggers allow you to set up automated HTTP requests to your endpoints on a scheduled basis. These triggers can be used to:

• Automate recurring tasks
• Perform health checks
• Schedule data synchronization
• Run cleanup jobs
• Generate reports
• Send scheduled notifications
• Execute any API calls that need to run at regular intervals

Trigger Functions can only be called on your custom domains.

Setting Up a Trigger

1. Navigate to Triggers

   Go to Application > Environment > Triggers

2. Create new trigger

   Click on New trigger button

3. Configure trigger

   Fill in the inputs in the modal:

   • Name: Descriptive name for the trigger
   • URL: The endpoint to call (must be on your custom domain)
   • Cron expression: When to run the trigger
   • HTTP Method: GET, POST, PUT, DELETE, etc.
   • Headers (optional): Custom headers to include
   • Body (optional): Request body for POST/PUT requests
4. Create trigger

   Click on Create button to activate the trigger

This will call the specified endpoint with the configured cron periodicity. The timezone is UTC.

Cron Expression Format

Periodic triggers use standard cron expressions to define schedules:

* * * * *
│ │ │ │ │
│ │ │ │ └─── Day of week (0-7, Sunday = 0 or 7)
│ │ │ └───── Month (1-12)
│ │ └─────── Day of month (1-31)
│ └───────── Hour (0-23)
└─────────── Minute (0-59)

Common Cron Examples

Every Hour

0 * * * *

Runs at the start of every hour

Every Day at Midnight

0 0 * * *

Runs daily at 00:00 UTC

Every Monday at 9 AM

0 9 * * 1

Runs every Monday at 09:00 UTC

Every 15 Minutes

*/15 * * * *

Runs every 15 minutes

More Examples

Schedule	Cron Expression	Description
Every 5 minutes	*/5 * * * *	Frequent monitoring
Every 30 minutes	*/30 * * * *	Regular checks
Every 6 hours	0 */6 * * *	Periodic sync
Daily at 2 AM	0 2 * * *	Nightly cleanup
Weekly on Sunday	0 0 * * 0	Weekly reports
First day of month	0 0 1 * *	Monthly tasks
Weekdays at 8 AM	0 8 * * 1-5	Business hours

Use Cases

Health Checks

{
  "name": "API Health Check",
  "url": "https://example.com/api/health",
  "cron": "*/5 * * * *",
  "method": "GET"
}

Data Synchronization

{
  "name": "Sync User Data",
  "url": "https://example.com/api/sync/users",
  "cron": "0 */6 * * *",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
  }
}

Cleanup Jobs

{
  "name": "Clean Old Sessions",
  "url": "https://example.com/api/cleanup/sessions",
  "cron": "0 2 * * *",
  "method": "POST"
}

Report Generation

{
  "name": "Weekly Report",
  "url": "https://example.com/api/reports/weekly",
  "cron": "0 0 * * 0",
  "method": "POST",
  "body": {
    "format": "pdf",
    "recipients": ["[e-mail]"]
  }
}

Debugging

Stormkit saves the request and response for each periodic task. You can view the last 25 logs for each trigger:

1. Locate trigger

   Find the trigger in your Triggers list

2. Open menu

   Expand the dot menu (...) next to the trigger

3. View logs

   Click on the Past triggers menu item

The logs include:

• Timestamp
• Request details (URL, method, headers, body)
• Response status code
• Response body
• Execution duration
• Any errors encountered

Logs are retained for the last 25 executions per trigger.

Best Practices

1. Use Idempotent Endpoints

Ensure your endpoints can be safely called multiple times:

// Good: Idempotent cleanup
app.post('/api/cleanup/sessions', async (req, res) => {
  await Session.deleteMany({ expiresAt: { $lt: new Date() } });
  res.json({ ok: true });
});

2. Implement Authentication

Secure your trigger endpoints:

const TRIGGER_SECRET = process.env.TRIGGER_SECRET;

app.post('/api/trigger/cleanup', async (req, res) => {
  const auth = req.headers.authorization;
  
  if (auth !== `Bearer ${TRIGGER_SECRET}`) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  // Process trigger
});

3. Handle Errors Gracefully

app.post('/api/trigger/sync', async (req, res) => {
  try {
    await syncData();
    res.json({ success: true });
  } catch (error) {
    console.error('Sync failed:', error);
    res.status(500).json({ error: error.message });
  }
});

4. Set Appropriate Timeouts

Ensure long-running tasks complete within timeout limits:

// For long tasks, process in batches
app.post('/api/trigger/process', async (req, res) => {
  const batch = await getBatch(100); // Process in small batches
  await processBatch(batch);
  res.json({ processed: batch.length });
});

5. Monitor Execution

Log trigger executions for monitoring:

app.post('/api/trigger/cleanup', async (req, res) => {
  const startTime = Date.now();
  
  const result = await performCleanup();
  
  const duration = Date.now() - startTime;
  console.log(`Cleanup completed in ${duration}ms:`, result);
  
  res.json({ duration, ...result });
});

Self-Hosting

If you are self-hosting Stormkit, the periodic jobs are handled by the workerserver.

Ensure the workerserver is running and properly configured to execute periodic triggers.

Limitations

• Custom domains only - Triggers must call endpoints on custom domains
• UTC timezone - All cron schedules run in UTC timezone
• Execution logs - Only the last 25 executions are stored
• Timeout - Triggered requests must complete within standard timeout limits

Troubleshooting

Trigger not firing

• Verify the cron expression is correct using a cron validator
• Check that the trigger is enabled
• Ensure the URL points to a custom domain (not preview URL)
• Review the trigger logs for errors

Endpoint returning errors

• Check the Past Triggers logs for error details
• Verify the endpoint URL is correct and accessible
• Ensure authentication headers are properly configured
• Check server logs for the endpoint

Wrong timing

• Remember: all schedules are in UTC timezone
• Convert your local time to UTC
• Verify the cron expression matches your intent
• Check Past Triggers for actual execution times

Timeout errors

• Optimize endpoint to complete faster
• Process data in smaller batches
• Consider async processing for long tasks
• Check server timeout configurations

Security Considerations

• Authentication - Always authenticate trigger requests
• Rate limiting - Implement rate limiting on trigger endpoints
• Validation - Validate all inputs even from scheduled triggers
• Secrets - Use environment variables for sensitive data
• HTTPS only - Always use HTTPS URLs for triggers