Skip to Content
Browse documentation

Writing and Installing Hooks

Install trusted local Eenos hook scripts with correct directories, executable permissions, filename ordering and bounded failure handling.

Choose an available hook, phase and script language. A script needs a working shebang or must be an executable binary. Python and PHP examples are provided in Hook Arguments and Payloads.

Directories and discovery

/var/eenos/hooks/createacct/
├── pre/
│   └── 10-check.py
└── post/
    ├── 10-notify.py
    └── 20-reconcile.py

The dispatcher looks at direct non-hidden entries in the phase directory, selects paths recognized as files and sorts full paths lexicographically. It does not recurse into subdirectories or filter by filename extension. A symlink to a file can also match; do not use links to untrusted targets. Use zero-padded filename prefixes for predictable ordering: 10 precedes 20, while lexical order is not numeric sorting.

There is no registration database or service restart requirement in the dispatcher: discovery occurs when the caller invokes that hook phase. A missing or empty directory does nothing. A correctly named directory alone cannot cause an event that the application never emits.

Install a reviewed script

Save the chosen Python example as /root/eenos-hook.py and test it with synthetic arguments before placing it in a live hook directory. For an administrator-managed account-creation post-hook, an example root-shell installation is:

install -d -o root -g root -m 0750 /var/eenos/hooks/createacct/post
install -o root -g root -m 0750 /root/eenos-hook.py /var/eenos/hooks/createacct/post/10-notify.py

These commands install a real callback when you run them; they are not needed to read or test the decoder example. Review the script before installation. Verify that the actual caller has directory traversal and execute permission; adapt a trusted group where your execution context requires it. Do not make the hook directory or script writable by hosting users or untrusted processes.

Use simple filenames and paths without spaces or shell metacharacters. The current dispatcher builds a shell command from the script path and arguments without shell-quoting each value. Keep hook locations and scripts administrator-controlled, treat input as data and use fixed argument-array subprocess calls if your script launches a tool.

The dispatcher does not check executable permission before attempting a file. A non-executable file can therefore be attempted and fail; chmod minus-execute is not a clean disable mechanism. To disable a script, move it outside both live pre/post discovery directories. Renaming it to .disabled as a suffix still leaves a matching non-hidden file and does not disable discovery.

Execution and failure behavior

The command runner captures stdout and stderr and writes non-empty output through the supplied operation logger. The dispatcher logs starting/stopping around the invocation, but does not check the returned process exit code. A nonzero exit can still be followed by a normal stopping message and the next script. Exceptions from launching/running a script are logged as an abort for that script and iteration continues.

JSON serialization and command preparation occur outside the per-script exception handler; not every possible dispatcher failure is suppressed. Do not use that behavior as a supported validation/veto mechanism. A hook receives no callback return channel for editing the parent data or deciding whether the operation proceeds.

Scripts run synchronously and sequentially. The runner has no timeout or automatic retry. Apply deadlines to network/subprocess work, avoid recursion into the same Eenos operation and plan for repeated events or partial external-system failures. Do not log full payloads, which may contain sensitive account/DNS configuration. Base64 is encoding, not encryption.

Verify an integration

Test the decoder offline, then test the specific operation in a controlled environment. Confirm the phase, delivered metadata, caller privileges and real payload shape. Check the underlying operation's outcome independently; the meaning of a post-hook varies by event. Use the caller's normal operation log for diagnostics rather than assuming a separate universal hook log file exists.