Actions
Forte Actions call one of your Services — asynchronously, at times you choose. An action is either recurring (it runs on a cron schedule) or one-time (it runs once at a specific moment). Each time an action runs, Forte sends an HTTP POST to a path on the service you chose and records the result as an invocation.
Actions are in beta. The API surface and console are stable for everyday use; expect additional scheduling and delivery options over time.
Use actions for nightly jobs, reminders, periodic syncs, cache warming, scheduled report generation, or any "call this endpoint later / on a timer" need — without running your own scheduler.
How Actions Work
You register an action with a target service and path (much like a payment trigger), an optional request body, and a schedule. The target service must belong to the same project. Forte calls that path on that schedule and keeps a history of every call. Actions are managed from your backend (the server-side forte.projects.* API with FORTE_API_TOKEN), the forte actions CLI, or the console — they belong to the project, not to a signed-in end user.
Schedule types
| Type | When it runs | Required fields |
|---|---|---|
| Recurring | Repeatedly, on a cron schedule evaluated in a timezone you choose, optionally bounded by a start/end window | cronExpression, timezone |
| One-time | Once, at a single future timestamp | scheduledAt |
- Timezone is an IANA identifier such as
America/New_York, so daylight-saving transitions are handled for you. - Active window (recurring only) — optionally restrict a recurring schedule to a start and/or end time. Outside the window, nothing fires. A start time in the past does not backfill missed runs — the schedule becomes active and the next run is simply the next matching time.
- Minimum cadence — an action runs at most once per minute. Schedules that would fire more often are rejected.
The request Forte sends
Every invocation is an HTTP POST to the path on the target service, with the request body you configured. Forte adds these headers:
| Header | Purpose |
|---|---|
X-Forte-Action-Id | The action that fired. |
X-Forte-Action-Invocation-Id | This specific invocation — use it to make your handler idempotent. |
X-Forte-Trusted | Set to 1 to prove the request genuinely came from Forte. |
Forte strips X-Forte-* headers from any inbound request it doesn't originate, so the presence of X-Forte-Trusted: 1 proves the call came from Forte. Validate it in your handler before acting — this is the same mechanism used by payment triggers.
Design your handler to be idempotent on the invocation id and to return a 2xx quickly. Do slow work in the background.
Retries
Mark an action retryable and Forte automatically retries a failed delivery — a non-2xx response, a timeout, or a connection error — on its internal retry policy. A non-retryable action is attempted once.
A failure of your endpoint is recorded on the invocation as a failed delivery; it does not indicate a problem with Forte.
Invocations
Each run of an action is recorded as an invocation you can list and inspect, with its status, number of attempts, the response code your endpoint returned, and timing.
| Status | Meaning |
|---|---|
PENDING / RUNNING / RETRYING | Scheduled, in progress, or waiting to retry. |
SUCCEEDED | Your endpoint returned a 2xx. |
FAILED | Your endpoint errored after all attempts. |
CANCELLED | You cancelled the invocation before it ran. |
MISSED | Forte did not run a scheduled occurrence on time. |
You can also:
- Invoke now — trigger an on-demand invocation to test your endpoint immediately.
- Cancel — cancel a still-pending invocation.
- Pause / resume — disable an action to stop its schedule without deleting it, then re-enable it later.
Quotas
Each project has a limit on the number of enabled actions. Pause or delete actions you no longer need to stay under the limit.
Next Steps
- Create your first action with the step-by-step guide
- Learn about Services to host the endpoint an action calls
- Review API Surfaces for where the server-side API token belongs