Set Up Triggers

A trigger defines what starts a workflow automatically. Apptor Flow supports four trigger types: webhook (HTTP event from an external service), schedule (cron-based timer), email (incoming message), and on-demand (manual or API call).

Prerequisites:

• A published workflow (triggers only fire against published versions)
• Relevant integrations configured where required (email trigger needs a Nylas connection)

---

Webhook Triggers

Webhook triggers start a flow when an external service sends an HTTP POST to a registered endpoint. The incoming payload is available as variables in the flow.

Webhook triggers use Webhook Registrations — endpoint definitions created in Admin → Webhooks. A flow links to an existing registration rather than generating its own URL.

Step 1 — Create a Webhook Registration (Admin)

Before setting up the trigger, a webhook registration must exist.

1. Go to Admin → Webhooks.
2. Click + New Webhook.
3. Enter a name and select the provider (GitHub, Stripe, Shopify, custom, etc.).
4. Choose the environment mode:
   • Same for all environments — one endpoint URL used for both Development and Production
   • Per environment — separate endpoint URLs for Development and Production, each with its own signing secret
5. Complete the provider-specific auth setup (signing secret, HMAC algorithm, etc.).
6. Click Save. The endpoint URL(s) are displayed — copy them.
7. Register the URL(s) in your external service:
   • Register the Development URL in your external service's test/sandbox webhook settings
   • Register the Production URL in your external service's live webhook settings

Step 2 — Link the Webhook to a Flow

1. Open the flow in the designer.
2. Click the Triggers button in the toolbar.
3. Click + Add Trigger.
4. Choose Webhook as the trigger type and click Next.
5. Select the webhook registration from the dropdown.
6. Optionally enter an Event Type Filter — if set, the trigger only fires when the incoming event matches (e.g. order.created). Leave empty to fire on all events.
7. Click Create Trigger.

Variables available in the flow

When the webhook fires, the following variables are automatically set:

Variable	Content
{webhookPayload}	The normalized JSON payload (provider-agnostic structure)
{webhookEventType}	The event type string (e.g. order.created, push)
{webhookHeaders}	All HTTP headers from the incoming request
{webhookProvider}	The provider name (e.g. GITHUB, STRIPE, CUSTOM)
{webhookEventId}	Unique event ID for idempotency tracking
{webhookTraceId}	Trace ID for debugging the full processing pipeline
{webhookRawBody}	The original request body (base64-encoded)
{webhookEventTimestamp}	Timestamp of the event from the provider (if available)

Access nested payload fields using dot notation:

Incoming JSON	Variable
{ "order": { "id": "123" } }	{webhookPayload.order.id}
{ "customer": { "email": "..." } }	{webhookPayload.customer.email}

Important notes

• The flow must be published for the webhook to execute it. An unpublished draft will not fire — even if the request arrives on the Development endpoint URL.
• The endpoint responds with HTTP 200 immediately — the flow executes asynchronously.
• Payload verification (HMAC signature check) happens before the flow is triggered. Invalid signatures are rejected silently.

Test with curl

Send a test POST to verify your webhook endpoint is reachable:

curl -X POST http://your-server/webhook/receive/YOUR_DEV_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "order": {"id": "test-123"}}'

Replace YOUR_DEV_TOKEN with the Development endpoint token from Admin → Webhooks. After sending, check Process Monitoring to confirm the execution appeared.

note

If your webhook registration uses signature verification, the test curl request will be rejected unless you compute the correct HMAC signature. For initial testing, temporarily set auth type to None or use the built-in test tool in Admin → Webhooks.

---

Cron / Schedule Triggers

Schedule triggers run a workflow automatically on a time-based schedule using cron expressions. This is handled by the scheduler module (JobRunr).

Set up a schedule trigger

1. Open a flow in the designer.
2. Click the Triggers tab.
3. Click Add Trigger.
4. Choose Schedule as the trigger type.
5. Enter a cron expression defining when the flow should run.
6. Click Save.

Cron expression examples

Expression	Meaning
0 9 * * 1-5	Every weekday at 9:00 AM
0 * * * *	Every hour on the hour
0 0 * * *	Every day at midnight
0 0 * * 1	Every Monday at midnight
*/15 * * * *	Every 15 minutes
0 8,17 * * 1-5	Weekdays at 8 AM and 5 PM

Cron expressions follow standard five-field format: minute hour day-of-month month day-of-week.

Notes

• The scheduler runs as a separate service. Verify it is running if scheduled flows are not firing.
• The flow must be published for schedules to execute it.
• Scheduled runs appear in Process Monitoring like any other execution.

---

Email Triggers

Email triggers start a workflow when a new email arrives at a monitored inbox. This requires a Nylas email integration configured in Connections.

Set up an email trigger

1. Open a flow in the designer.
2. Click the Triggers tab.
3. Click Add Trigger.
4. Choose Email as the trigger type.
5. Select your Nylas email integration from the connection selector.
6. Configure any filtering options (e.g., subject contains, sender matches).
7. Click Save.

Available email variables

When an email arrives and triggers the flow, the following variables are available:

Variable	Content
{emailSubject}	The subject line of the email
{emailBody}	The plain-text body of the email
{emailSender}	The sender's email address
{emailRecipients}	The recipient addresses

Notes

• Requires a Nylas API integration — see Connect Services for setup.
• The flow must be published to process incoming emails.

---

On-Demand and API Triggers

On-demand triggers let you start a workflow manually or programmatically. This is useful for testing, for user-initiated actions, and for integrating with your own applications.

Run manually in the designer

Click the green Execute button in the designer toolbar. If the flow has input variables defined, a dialog opens for you to provide values before executing. Save any unsaved changes first — Execute is disabled until the flow is saved.

Trigger via API

Send a POST request to the process start endpoint:

curl -X POST http://your-server/process/start \
  -H "Content-Type: application/json" \
  -H "X-API-Key: apk_YOUR_KEY_ID_YOUR_SECRET" \
  -d '{
    "processId": "YOUR_FLOW_UUID",
    "data": {
      "inputField": "value",
      "anotherField": "value"
    }
  }'

Replace:

• apk_YOUR_KEY_ID_YOUR_SECRET with a valid API key (see Manage Access to create one)
• YOUR_FLOW_UUID with the process ID shown in the flow settings
• The data object with whatever input variables your flow expects

Notes

• API key format is apk_{keyId}_{secret} passed as the X-API-Key header.
• The processId is the UUID of the flow, not its display name. Find it in the flow settings or URL.
• Data passed in the data object becomes available as top-level variables in the flow.
• API calls always run the published version of the flow.