Skip to Content
Browse documentation

Hook Arguments and Payloads

Decode Eenos key=value hook arguments and base64 JSON safely with standalone Python and PHP examples and synthetic local tests.

Hooks are local executable scripts, not HTTP endpoints. The dispatcher sends these arguments after the script path. There are no --data flags, request headers, environment-variable credentials or stdin payload in this interface.

Arguments

ArgumentMeaning
data=VALUEBase64-encoded JSON copy of the caller's data. Required by the dispatcher contract.
action=VALUECREATE, UPDATE or DELETE; normalized to uppercase by the dispatcher.
panel=VALUEwap, rapp or uapp, as supplied by the caller.
domain=VALUEIncluded when the caller supplies a non-empty domain.
user=VALUEIncluded when the caller supplies a non-empty account name. It does not change OS privileges.

Split each argument at its first equals sign: base64 padding can contain additional equals signs. Decode base64, decode UTF-8 and then parse JSON. Do not evaluate the text as code. Data is a copy in a separate process; changing it does not mutate the parent operation's dictionary.

The dispatcher uses JSON's default ASCII escaping before base64 encoding, so non-ASCII text is represented through JSON escapes and restored by a proper JSON parser. An empty payload object is valid for DNS DELETE. Other payload shapes depend on the event/caller, and optional metadata must not be assumed present. There is no phase, function_name, result or success argument; the installed script's directory determines the event/phase it handles.

Python example

Save this complete script using the installed Eenos interpreter in its shebang. It validates metadata and a JSON object, then reports only a small receipt; add your own bounded, idempotent integration work at the marked location.

#!/usr/local/eenos/bin/python
import base64
import binascii
import json
import sys

try:
    values = {}
    for argument in sys.argv[1:]:
        key, separator, value = argument.partition("=")
        if not separator or key not in {"data", "action", "panel", "domain", "user"} or key in values:
            raise ValueError("Invalid hook argument")
        values[key] = value
    if values.get("action") not in {"CREATE", "UPDATE", "DELETE"}:
        raise ValueError("Invalid action")
    if values.get("panel") not in {"wap", "rapp", "uapp"}:
        raise ValueError("Invalid panel")
    payload = json.loads(base64.b64decode(values["data"], validate=True).decode("utf-8"))
    if not isinstance(payload, dict):
        raise ValueError("Expected a JSON object")
    # Add bounded, idempotent integration work here. Do not evaluate payload text.
    print(json.dumps({"message": "Hook received", "action": values["action"],
                      "panel": values["panel"], "domain": values.get("domain"),
                      "user": values.get("user")}))
except (KeyError, ValueError, UnicodeError, binascii.Error) as error:
    print(f"Hook input rejected: {error}", file=sys.stderr)
    raise SystemExit(1)

PHP example

This complete example uses PHP 8 CLI (PHP 7.3 or later supports its JSON exception flags). Verify that the shebang resolves to the intended PHP CLI binary on your server.

#!/usr/bin/php
<?php
try {
    $values = [];
    foreach (array_slice($argv, 1) as $argument) {
        $parts = explode('=', $argument, 2);
        if (count($parts) !== 2 || !in_array($parts[0], ['data', 'action', 'panel', 'domain', 'user'], true)
                || array_key_exists($parts[0], $values)) {
            throw new RuntimeException('Invalid hook argument');
        }
        $values[$parts[0]] = $parts[1];
    }
    if (!in_array($values['action'] ?? null, ['CREATE', 'UPDATE', 'DELETE'], true)
            || !in_array($values['panel'] ?? null, ['wap', 'rapp', 'uapp'], true)) {
        throw new RuntimeException('Invalid action or panel');
    }
    $decoded = base64_decode($values['data'] ?? '', true);
    if ($decoded === false) {
        throw new RuntimeException('Invalid base64');
    }
    $payload = json_decode($decoded, false, 512, JSON_THROW_ON_ERROR);
    if (!is_object($payload)) {
        throw new RuntimeException('Expected a JSON object');
    }
    // Add bounded, idempotent integration work here; do not evaluate payload text.
    echo json_encode(['message' => 'Hook received', 'action' => $values['action'],
        'panel' => $values['panel'], 'domain' => $values['domain'] ?? null,
        'user' => $values['user'] ?? null], JSON_THROW_ON_ERROR) . PHP_EOL;
} catch (Throwable $error) {
    fwrite(STDERR, 'Hook input rejected: ' . $error->getMessage() . PHP_EOL);
    exit(1);
}

Offline sample

Save the Python example as /root/eenos-hook.py outside the live hook directories. This command supplies the synthetic object {"example":true}; it does not create or change an Eenos account:

/usr/local/eenos/bin/python /root/eenos-hook.py \
  'data=eyJleGFtcGxlIjp0cnVlfQ==' \
  action=CREATE panel=wap domain=example.com user=exampleuser

The example prints a receipt containing the action, panel and supplied identities, without printing the payload. To test the PHP version saved as /root/eenos-hook.php, use the same arguments after /usr/bin/php /root/eenos-hook.php.

A nonzero exit from these examples indicates invalid sample input. During real hook dispatch, the manager ignores that exit code; it is not a request to reject or roll back the parent operation. See execution behavior and the individual event's timing notes.