Loading

Webhooks, Functions and Extension Steps

The Other systems group covers what the built-in steps cannot do on their own: calling another system over HTTPS, working out a value with one of the workflow library's functions, or running custom code from a published extension. Because these steps run with the engine's rights rather than the editor's, only an architect may add or change them.

Where to find it

Architect Panel → Automation:

  • Workflow Builder — Webhook, PHP function and Extension step are in the Other systems group of the Steps palette
  • Extensions — where the code an Extension step runs is approved and put live

Webhook

  1. Enter the URL. It must start with https://; redirects are not followed. It may use placeholders.
  2. Choose the Method: POST, PUT or PATCH.
  3. Add any Headers (a name and a value, such as an authorisation token). Content-Type: application/json is always sent.
  4. Leave Body blank to send the record as JSON, or write the body with placeholders. A body that is not valid JSON is sent as written, and Validate warns.
  5. Set Give up after (seconds): 15 when blank, between 1 and 120.
  6. Connect Next and On error.

A failed call goes down On error when it is connected; otherwise the run fails. Tick Carry on down 'next' even if the call fails to ignore failures altogether. Later steps can read the reply as {{webhook.step.status}}, {{webhook.step.body}} and {{webhook.step.json.key}}, and after a failure the reason as {{webhook.step.error}}.

PHP function

The Function list offers the workflow library's functions (shown as "Library: …") and any function your installation has declared for workflows. The library needs no code:

  • Days between two dates: reads from and to (default today), writes days.
  • Percentage of a total: reads value and of, writes percent and over.
  • Work out a reorder quantity: reads on_hand, reorder_point, reorder_qty and max_level, writes order_qty and below.
  • ERP: stock on hand of an item, ERP: is an item at or below its reorder point?, ERP: a project's spend against its budget, ERP: three-way match a supplier invoice now, ERP: accept a supplier invoice's match differences and ERP: run a company's reminder ladder (dunning): ask the ERP engines the same questions their own screens do.

The help under the list says what the chosen function reads and writes. To use one:

  1. Add a Set variables step that sets the names the function reads.
  2. Add the PHP function step, choose the function, and set Works on to "The run's variables".
  3. Use its answers as {{vars.name}}, for example in a Condition.

Works on can also be the run's record, the current row of a For each, or what a Look up found. A function's changes are seen by later steps but not saved; add an Update record step to save them. A missing or non-numeric input fails the step with a reason.

Extension step

  1. Have the extension written, approved and published for the workflow step hook; see Extensions.
  2. Add an Extension step and choose the Extension.
  3. Add Settings for the extension as names and values; values may use placeholders.
  4. Connect Next and On error.

A failure, a timeout or an extension that has been switched off goes down On error when it is connected; otherwise the run fails with the reason.

AI decision and AI check

The AI decisions group asks TypeSafe Jev to choose an option or judge a statement from fields of the record, routing unsure answers to a person. They are documented in AI Decision and AI Check Workflow Steps.

What goes wrong

  • "Webhooks are sent over HTTPS only": the URL starts with http://.
  • "is not a custom function this installation allows": the function is not a library function and has not been declared for workflows.
  • An editor cannot save. Only an architect may add or change these three steps; the editor role cannot.
  • The function's answer is not saved. Functions change the run's values only; add an Update record step.
  • Simulate did not call the other system. By design: webhooks, extension steps and custom functions are described in a simulation, not run.

Worked example

A records team must tell its finance system when a contract is marked Ready. The webhook-on-change template gives them a Condition on the status, a Webhook to https://finance.example.com/hooks/contracts with the record as JSON, on Next an Update record that writes "sent", the time and the HTTP status into the contract's sync field, and on On error an Update record that writes "failed" plus a Notify telling the administrators the reason and the HTTP status. An architect adds the finance system's token as a header before publishing.

Recommendations

  • Always connect On error on a Webhook.
  • Use library functions before asking for custom code.
  • Keep secrets in headers, not in the URL.
  • Record the outcome of each call on the record so it can be resent.