Before you start
Workflow
- 1Choose a published action and an authorized management client. Creating or enabling a trigger requires invocation permission and authority to delegate every declared capability.
- 2The setup below reads an existing action. The schedule example reuses client and action and assumes that action accepts a region string; adapt input to its actual published contract.
- 3Review the schedule and destination before creating it. Check isEnabled, disabledReason, and lastRun after creation and after action publication.
Example
import { PermuteClient } from '@permute/sdk';
function required(name: string): string {
const value = process.env[name]?.trim();
if (!value) throw new Error('Set ' + name);
return value;
}
const client = new PermuteClient({
apiKey: required('PERMUTE_API_KEY'),
}).withWorkspace(required('PERMUTE_WORKSPACE_ID'));
const action = await client.actions.get(required('PERMUTE_ACTION_ID'));
console.log(action.id, action.name);Run an action on a schedule
A scheduled Business Action uses automation access: it runs at a fixed time with the same input each run, under the workspace system identity and within the action’s published capabilities. The management client that creates, edits, or enables the trigger needs invocation permission and authority to delegate every declared capability. The input must match the published input contract. Once enabled, the schedule can continue after the person who configured it signs out; pause the trigger to stop future scheduled runs.
Schedule values are whole numbers: hourly { minute }, daily { hour, minute }, weekly { hour, minute, dayOfWeek } with 0 as Sunday, and monthly { hour, minute, dayOfMonth }. Use dayOfMonth 1–28 to run in every month. Add timeZone, an IANA name such as America/Chicago, to keep the local time across daylight saving changes; without it the schedule uses UTC. Runs start within about five minutes of their time; until then, nextRunAt stays at the due time. Missed times run once, as the newest missed time. Each run uses the request ID <triggerId>_<time in epoch ms>, so a retried time never runs twice.
Each run uses the action’s current published revision and rechecks input. Publishing an action with an enabled trigger requires the publisher to be able to invoke the new revision, but it does not check trigger input, so a trigger whose input no longer matches turns off at its next run. A deleted or unpublished action, input which no longer matches, or a time which cannot start for 24 hours turns the trigger off: isEnabled becomes false, nextRunAt becomes null, and disabledReason gives the cause. Turning off records no run, so check isEnabled and disabledReason as well as lastRun. A failed run keeps the trigger on and is not retried.
Set isEnabled: false to pause: nextRunAt becomes null and disabledReason stays null, which tells a pause apart from an automatic disable. Updating config replaces the whole config and, like enabling, repeats the access and input checks; fix the cause before you set isEnabled: true. lastRun and runs (the newest 50) show each run’s request ID, status, revision, and failure, not its output or written records. To keep a run’s results, write them inside the handler, for example to a managed database table; saved receipts belong to their caller, so invoking with a run’s request ID runs the action again. Scheduled runs pass caller { type: 'system', id: '<triggerId>' }, and handlers can read the current time with Date.
// The existing published action must accept { region: 'EMEA' }.
// This creates a recurring schedule; it does not refresh upstream sources.
const trigger = await client.actionTriggers.create(action.id, {
type: 'schedule',
config: { schedule: { type: 'weekly', dayOfWeek: 1, hour: 9, minute: 0 }, input: { region: 'EMEA' } },
});
const { lastRun, disabledReason } = await client.actionTriggers.get(action.id, trigger.id);Run an action from a webhook
A webhook trigger runs the published action each time its secret URL receives a POST, with the same access checks as a schedule trigger. The create response returns the URL in webhookUrl, and any update which sends isEnabled: true or config returns it again; pausing and reads never include it. In the web app, people who can change the trigger can also show the URL on the trigger’s page. The URL is the only check, so treat it as a secret, and delete the trigger and create another to replace it.
Each run receives the fixed input plus event { body, headers, query, receivedAt }. body is the raw request text decoded as UTF-8; headers and query map names to string values, with lowercase header names and a repeated query key joined by commas; receivedAt is an ISO 8601 time. The input contract must accept event. Creation checks it with an empty placeholder request, so rules on the event’s contents, such as a required signature header, are checked against each real request instead. The fixed input cannot use event (400 invalid_request). Headers also include ones which Permute’s CDN adds, among them the sender’s IP address and location (x-forwarded-for and cloudfront-viewer-*); host is an internal name, so use x-forwarded-host to rebuild the public URL.
The URL accepts POST only and never returns the run’s result. It replies 200 {"data":{"status":"queued"}} once the run is queued, 200 {"data":{"status":"ignored"}} while the trigger is paused or disabled, 404 {"error":"Not found."} for an unknown trigger or wrong token, and 413 when the whole input, including the request headers, would exceed 100 KB (100,000 bytes). A request which fails the contract fails only its run; senders which require a setup handshake are not supported.
Each run’s request ID is <triggerId>_<deliveryId> and its caller is { type: 'system', id: '<triggerId>' }. A queue retry runs once, but a sender which resends after a lost reply starts a second run, so deduplicate on the sender’s delivery ID (such as X-GitHub-Delivery) when that matters. nextRunAt is always null for a webhook trigger; use isEnabled to see whether it is paused.
Handlers have no Node or Web Crypto, TextEncoder or Buffer, so a signature check needs a small JavaScript HMAC-SHA256 implementation in the handler code. A secret written in action code is readable by people with View code permission and stays in older revisions. For GitHub, set the webhook’s content type to application/json and compare X-Hub-Signature-256 (sha256= and the hex HMAC of the raw body); GitHub’s first ping arrives as an ordinary request.
// The published action's inputSchema must accept event, for example:
// { type: 'object', properties: { event: eventSchema }, required: ['event'] }
const eventSchema = {
type: 'object',
properties: {
body: { type: 'string' },
headers: { type: 'object', additionalProperties: { type: 'string' } },
query: { type: 'object', additionalProperties: { type: 'string' } },
receivedAt: { type: 'string' },
},
required: ['body', 'headers', 'query', 'receivedAt'],
};
const hook = await client.actionTriggers.create(action.id, { type: 'webhook', config: { input: {} } });
// Give hook.webhookUrl to the sender and keep it secret.