For the complete documentation index, see llms.txt. This page is also available as Markdown.

The callback contract

The unified callback contract — the info map every callback receives, the access tokens to call back into the fylr API, the plugin_user mechanism, and the error format.

Callbacks run server-side and frequently need to call back into the fylr API — to read the base config, load or write objects, or search. For this, every callback receives the same set of context fields, the callback contract, independent of which hook runs.

Where the contract fields live

  • For db_pre_save, transition_db_pre_save, collection upload and the export hooks, the payload carries the hook's own data next to the contract fields, which live under the info key: info.api_url, info.api_user_access_token, …

  • For extensions the request body is streamed to STDIN as-is, so the contract fields are only available via the %info.json% argument.

  • Any callback can additionally receive the info map as a command argument by passing %info.json% in its exec args — it is substituted as an inline JSON string (parse process.argv[n] directly; it is not a file path).

The info map

Property
Presence
Description

api_url

always

Base URL to call back into the API. Append /api/v1/… to reach an endpoint.

external_url

always

The configured external URL of the fylr instance — for building links meant for humans.

api_user_access_token

always¹

OAuth2 access token to call the API as the user the current API call runs as.

api_user

when a user context exists

The current API user (the who).

request

when the hook runs inside an HTTP request

Information about the triggering request: url, host, method, query, header.

config

plugin callbacks²

config.system — the base config visible to the plugin — and config.plugin.<plugin-name> — the plugin's own base-config additions, decrypted.

plugin_user_access_token

only if plugin_user is configured

Access token of the configured plugin user (see below).

plugin_user

only if plugin_user is configured

The plugin user (the who) for plugin_user_access_token.

¹ For workflow webhooks the token is removed from the payload unless the webhook enables include access token. ² Workflow webhooks run without a plugin, so their payload has no config key.

Individual hooks add more keys — for example the transition action's info object (transition_db_pre_save), file / collection / collection_config (collection upload), or export / transport / plugin_action (export, export_transport).

Access tokens

A callback always gets a token for the current API user, and additionally a token for the plugin user when one is configured — never one or the other.

These tokens are unbound and short-lived. fylr binds a browser session token to the browser via the fylr-browser-id cookie, so a plugin replaying such a token server-side — without that cookie — would be rejected by session binding. For a browser-bound session fylr therefore mints a fresh, session-binding-free token for the callback; tokens of regular API clients are already unbound and are passed through. Freshly minted tokens are revoked once the callback returns — treat them as valid only for the duration of the callback and do not persist them.

The plugin user

By default a callback acts as the user who triggered the API call — with that user's permissions. When a callback needs its own, well-defined set of permissions (for example to write objects the triggering user cannot), the manifest entry declares a plugin user:

base_config names a parameter of type user in the plugin's own base-config additions, as <section>.<parameter>. The administrator selects the acting user there in the base configuration. At run time fylr issues an unbound token for that user and passes it as plugin_user_access_token / plugin_user. If no user is configured, or the configured user is the calling user, the plugin user falls back to the current API user (both tokens are then equal).

The plugin user is supported on db_pre_save step callbacks, transition_db_pre_save, collection-upload objects callbacks, export callbacks and extensions.

Calling back into the API

Errors

A callback signals an error in one of two ways:

  • Exit with a non-zero exit code. If STDOUT contains an API-error JSON (see below, without the error wrapper), that error is used; otherwise a generic error naming the failed callback is reported.

  • Exit zero and return the API-error JSON under a top-level error key in the response body:

An API error returned either way is passed to the API client as-is — with the plugin's error code, parameters and status code — so a plugin can produce first-class, localized validation errors:

Any other failure (non-zero exit without an error JSON, invalid or empty response body) is wrapped in a generic error naming the failed runner. What an error does to the running operation is described on each hook's page.

See also

Last updated