Webhooks & Scheduling

Trigger pipelines via HTTP webhooks or schedule them to run automatically with cron expressions.

FlowMason Studio provides powerful automation capabilities through webhooks (event-driven triggers) and scheduling (time-based triggers).

Webhooks

Webhooks allow external systems to trigger pipeline executions via HTTP:

Trigger pipelines from external services (GitHub, Slack, Stripe, etc.)
Build event-driven automation workflows
Integrate with CI/CD pipelines
Create public APIs backed by FlowMason pipelines

Creating a Webhook

POST /api/v1/webhooks
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "name": "GitHub Push Handler",
  "pipeline_id": "my-pipeline-id",
  "input_mapping": {
    "repository.full_name": "repo",
    "commits": "commits",
    "pusher.name": "author"
  },
  "default_inputs": {
    "environment": "production"
  },
  "require_auth": true,
  "auth_header": "X-Hub-Signature-256",
  "auth_secret": "my-webhook-secret",
  "async_mode": true
}

Response includes the webhook URL:

{
  "id": "wh-abc123",
  "webhook_url": "https://studio.example.com/api/v1/webhook/aBcDeFgHiJkLmNoPqRsTuVwXyZ",
  "enabled": true
}

Triggering a Webhook

curl -X POST https://studio.example.com/api/v1/webhook/aBcDeFgHiJkLmNoPqRsTuVwXyZ \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: my-webhook-secret" \
  -d '{"repository": {"full_name": "user/repo"}, "commits": [...]}'

Async vs Sync Mode

Async Mode (Default) - Returns immediately with a run ID:

{
  "status": "accepted",
  "run_id": "run-xyz789"
}

Sync Mode - Waits for pipeline completion:

{
  "status": "completed",
  "run_id": "run-xyz789",
  "result": { ... }
}

Input Mapping

Map webhook payload fields to pipeline inputs using dot notation:

Webhook Payload	Input Mapping	Pipeline Input
`{"user": {"id": 123}}`	`"user.id": "userId"`	`{"userId": 123}`
`{"items": [1, 2, 3]}`	`"items": "data"`	`{"data": [1, 2, 3]}`

Common Integrations

Service	Auth Header
GitHub	`X-Hub-Signature-256`
Stripe	`Stripe-Signature`
Slack	`X-Slack-Signature`

Scheduling

The built-in scheduler runs pipelines automatically based on cron expressions.

Creating a Schedule

curl -X POST http://localhost:8999/api/v1/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Report",
    "pipeline_id": "abc123",
    "pipeline_name": "generate-report",
    "cron_expression": "0 9 * * *",
    "timezone": "America/New_York",
    "inputs": {
      "format": "pdf",
      "recipients": ["[email protected]"]
    },
    "description": "Generate daily report at 9am ET"
  }'

Cron Expressions

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Common Schedules

Expression	Description
`0 9 * * *`	Daily at 9:00 AM
`0 9 * * 1-5`	Weekdays at 9:00 AM
`/15 * * *`	Every 15 minutes
`0 /2 * *`	Every 2 hours
`0 0 * * 0`	Weekly on Sunday at midnight
`0 0 1 * *`	Monthly on the 1st
`0 6,12,18 * * *`	At 6am, 12pm, and 6pm daily

Validate Expression

curl "http://localhost:8999/api/v1/schedules/cron/validate?expression=0%209%20*%20*%20*&timezone=America/New_York"

Returns next 5 scheduled runs:

{
  "valid": true,
  "next_runs": [
    "2025-01-15T09:00:00-05:00",
    "2025-01-16T09:00:00-05:00",
    "2025-01-17T09:00:00-05:00"
  ]
}

Managing Schedules

# List all schedules
curl http://localhost:8999/api/v1/schedules

# Enable/disable
curl -X POST http://localhost:8999/api/v1/schedules/{id}/disable
curl -X POST http://localhost:8999/api/v1/schedules/{id}/enable

# Manual trigger (doesn't affect next scheduled run)
curl -X POST http://localhost:8999/api/v1/schedules/{id}/trigger

# View run history
curl http://localhost:8999/api/v1/schedules/{id}/history

Timezones

Schedules support IANA timezone names:

UTC - Coordinated Universal Time
America/New_York - Eastern Time
America/Los_Angeles - Pacific Time
Europe/London - British Time
Asia/Tokyo - Japan Standard Time

Example: GitHub CI Integration

Create webhook:

{
  "name": "Deploy on Push to Main",
  "pipeline_id": "deploy-pipeline",
  "input_mapping": {
    "ref": "branch",
    "repository.full_name": "repo",
    "head_commit.message": "commit_message"
  },
  "auth_header": "X-Hub-Signature-256",
  "auth_secret": "github-webhook-secret"
}

Configure in GitHub Settings > Webhooks:
- Payload URL: Copy webhook_url from response
- Content type: application/json
- Secret: github-webhook-secret
- Events: Push events
Pipeline receives:

{
  "branch": "refs/heads/main",
  "repo": "user/my-app",
  "commit_message": "Fix bug in login"
}

Security Best Practices

Always use authentication in production
Validate webhook signatures for external services
Use HTTPS for webhook URLs
Regenerate tokens if compromised
Monitor invocation logs for suspicious activity
Set appropriate timeouts for sync mode