Automations

Automations let Tillor carry out actions itself, such as creating tasks or calling your system. The user guide is at Automations. This page describes what an integrator sees: the message from the Send webhook step, the API request to your own URL or to the Tillor API, and how a flow is built if you manage it through the API.

Send webhookCopy link to this section

The Send webhook step delivers a custom message to one of the organisation's webhooks. It is the same delivery as for ordinary webhook events, with the same signature.

The messageCopy link to this section

The step does a POST with Content-Type: application/json and these headers:

The body has the same envelope as the webhook payload:

{
  "event": "automation.invoice_unpaid",
  "data": {
    "invoice": "2026-0042",
    "amountOutstanding": 125.5
  },
  "timestamp": 1735689600000,
  "traceId": "0b0f7c0e-5d3c-4c1e-9b8a-7f1e2a3b4c5d",
  "triggeredBy": null
}

There is no spanId. The webhook does not have to be subscribed to an event key: a message from an automation is always delivered to the chosen endpoint, as long as it exists and is enabled.

How to verify the signature is described under Verifying the signature.

Attempts and outcomeCopy link to this section

Tillor makes up to 5 attempts within the step, waiting 1, 2, 4 and 8 seconds between them. An attempt counts as successful on a 2xx status. A target that is blocked, for example an internal address, also counts as a failed attempt.

• If one of the attempts succeeds, the flow continues through the Succeeded exit
• If all five fail, the flow continues through Failed. The message is then retried in the background according to the schedule under Delivery behaviour and retries. If such a later attempt succeeds, it no longer shows up in the run, because the run has already moved on

If the webhook no longer exists or is disabled, the step does not go through Failed. The run then stops with the status Failed.

API request to your own URLCopy link to this section

With API request and Send to set to Custom URL, an automation sends an HTTP request to your server.

A response with a 2xx status continues through Succeeded, any other status through Failed. If the server cannot be reached, or exceeds the timeout, the run stops with the status Failed.

API request to the Tillor APICopy link to this section

With Send to set to Tillor API, the automation calls the API of its own organisation. You only give a path, for example /tasks, and Tillor places it after /api/orgs/{orgId}. Your API reference is at OpenAPI.

• Identity: the request is executed as the organisation's Workflow user. That user has all permissions within that organisation and nowhere else. Changes are therefore recorded under the name Workflow
• No key needed: Tillor makes the call itself, without an API key and without going over the internet
• Path: must start with a single /. //, .. and \ are not allowed. A query string is allowed, for example /tasks?terrainId=…&limit=1. Variables in the path are filled in encoded
• Blocked: the paths /automations and /automation-runs are refused, also with a query string, capital letters, a trailing / or percent-encoding. An automation cannot manage automations
• Body: JSON, for POST, PUT and PATCH. For GET and DELETE it is not sent
• Picker: in the editor there is Pick an API endpoint with the operations from the OpenAPI specification. Internal operations are not listed. If you pick one, Tillor fills in the method, path and an example body
• Failure: a 2xx response continues through Succeeded. An error status, including a 404 for a path that does not exist, goes through Failed

The response in later stepsCopy link to this section

After the request these variables are available:

A second API request in the same flow replaces response. The variables work as described under Variables and templates.

The structure of a flowCopy link to this section

You can also create and change automations through the API. The operations are in OpenAPI under the tag automations. Reading requires the permission automations:read, creating and changing automations:write (or all permissions). The Workflow user itself can never call them. It may be easier to build a flow in the editor and read it as an example.

A new automation is always disabled. Enabling it through enabled does not work as long as the flow has open problems, and an enabled flow cannot be saved with problems.

The definition consists of steps (nodes), lines (edges) and optionally notes (notes). Maximum 100 steps, 200 lines and 50 notes.

{
  "nodes": [
    {
      "id": "trigger",
      "type": "trigger",
      "label": "",
      "position": { "x": 0, "y": 0 },
      "config": { "source": "event", "eventKey": "occupation:ended" }
    },
    {
      "id": "task",
      "type": "taskCreate",
      "label": "",
      "position": { "x": 0, "y": 190 },
      "config": { "title": "Controleer {occupation.terrain.name}", "priority": "HIGH" }
    }
  ],
  "edges": [
    { "id": "trigger:out:task", "source": "trigger", "target": "task", "sourceHandle": "out" }
  ],
  "notes": [
    {
      "id": "note_1",
      "text": "Maakt na elk vertrek een controletaak.",
      "position": { "x": 340, "y": 0 },
      "width": 240,
      "height": 140
    }
  ]
}

A note (notes) is an explanation on the canvas. It is never executed and has no lines. text is at most 2000 characters, width and height are in pixels.

A line has a sourceHandle: the exit of the step it comes from.

Every action except webhookSend and httpRequest gets an extra exit error as soon as continueOnError in the config is set to true. Without that setting a failed action stops the run. With that setting the flow continues through error, with {error.message} and {error.step} as variables for the steps after it. The exit skipped is used when a step had nothing to do, and out is then the ordinary exit.

For forEach, the exit each starts a separate run per item for the steps after it, and the exit done is the ordinary continuation of the flow itself.

An exit may lead to several steps. The run itself continues with the first line and starts a separate run for every other line with the same data, which runs in parallel (like the exit each of forEach). Lines that form a loop are refused in the editor. A flow has exactly one trigger.

Settings per stepCopy link to this section

The fields under config are the fields from the editor. Text fields accept variables between curly braces.

conditions has the form { "match": "all" or "any", "rules": [...] }. Each rule is { "id", "field", "operator", "value", "values" }. operator is is, isNot, contains, greaterThan, lessThan, isOneOf, isEmpty or isNotEmpty. You only use values with isOneOf. An empty list of rules lets everything through.

Start an automation with a webhookCopy link to this section

An automation with the trigger webhook starts on a POST to its own address:

curl -X POST "https://tillor.eu/api/orgs/org_abc123/automation-hooks/aut_xxx/<token>?bron=website" \
  -H "Content-Type: application/json" \
  -d '{"email":"jan@voorbeeld.nl","aankomst":"2026-07-14"}'

• The full address is in the editor at the trigger, or via GET /automations/{id}/webhook-url (with automations:read). The token is the secret; a header for authentication is not needed
• The JSON body becomes the variable body, the query string query, and the time receivedAt
• The answer is 200 with { "accepted": true } as soon as the run has started. A wrong, replaced or disabled address gives 404, a body above 100 KB gives 400
• Many calls shortly after each other are not refused: every valid call starts a run. Use Ignore repeats at the trigger if the same call can arrive twice, see Ignore repeats

An automation cannot call its own webhook through an API request to the Tillor API.

Choose a decision through the APICopy link to this section

The task of an Ask for a decision step has one action per option you set in the step. Fetch the task to see the actions with their id, and choose one with POST /tasks/{id}/actions/{actionId}/choose. If the option asks for a note, send it along as { "note": "..." }. The choice is final: it completes the task and continues the automation along the exit of that option. Assigned colleagues (also through a group) and administrators may choose. See the OpenAPI for the details.

Read moreCopy link to this section

• Webhooks for signature, retries and the list of events
• HTTP API for authentication and the organisation context
• Variables and templates for the user guide