16.1.1.14. Event endpoints

The event-handling REST API manages event handler bindings: which handler module reacts to which event, on which condition, with which action and options. See Event Handler for the conceptual chapter covering the available handler modules and their actions.

All endpoints require admin authentication. Read access for the binding list and the lookup endpoints (handler module positions, actions, conditions) is gated by the admin policy action eventhandling_read; create, update, enable, disable and delete are gated by eventhandling_write.

GET /event/(eventid)
GET /event/

Return event handler bindings, or one of two special introspection results, depending on the path:

  • /event/ — return all configured event handler bindings.

  • /event/<eventid> — return the binding with the given numeric id.

  • /event/available — return the list of event names privacyIDEA emits, as a flat list of strings. (Special path; no binding lookup.)

  • /event/handlermodules — return the list of available handler module identifiers (e.g. UserNotification, Token, Federation, Counter, …). (Special path; no binding lookup.)

Requires admin authentication and the policy action eventhandling_read.

Parameters:

  • eventid – optional path component, the numeric id of a binding, or one of the literal strings available / handlermodules for the special introspection results.

Status Codes:

  • 200 OK – list of binding dicts, list of event names, list of handler module names, or a single binding dict — depending on the path.

GET /event/positions/(handlermodule)

Return the positions a handler module supports — typically pre and/or post, indicating where in the request lifecycle the handler can fire.

Requires admin authentication and the policy action eventhandling_read.

Parameters:

  • handlermodule – path component, the handler module identifier (e.g. UserNotification).

Status Codes:

  • 200 OK – list of position names in result.value.

GET /event/defaults/(handlermodule)

Return the values a new binding of a handler module starts with, for the settings that are not specific to an action.

Currently this is abort_on_error, which is True for a handler whose result the request itself consumes: continuing without such a handler changes what the client receives, so a new binding of it should not be best-effort. The stored binding decides at runtime; this is only the value it is created with.

Requires admin authentication and the policy action eventhandling_read.

Parameters:

  • handlermodule – path component, the handler module identifier (e.g. Federation).

Status Codes:

  • 200 OK – dict of default values in result.value.

GET /event/actions/(handlermodule)

Return the actions a handler module supports. Each entry includes the action name and any per-action option schema the WebUI uses to render its form.

Requires admin authentication and the policy action eventhandling_read.

Parameters:

  • handlermodule – path component, the handler module identifier (e.g. UserNotification).

Status Codes:

  • 200 OK – dict of action descriptors in result.value.

GET /event/conditions/(handlermodule)

Return the conditions a handler module supports — the predicates that can gate whether the handler fires for a given event.

Requires admin authentication and the policy action eventhandling_read.

Parameters:

  • handlermodule – path component, the handler module identifier (e.g. UserNotification).

Status Codes:

  • 200 OK – dict of condition descriptors in result.value.

POST /event

Create or update an event handler binding. Pass an existing id to update; omit it to create a new binding.

Warning

Updates are only partially incremental:

  • position, ordering and active fall back to their defaults (post, 0 and True) if omitted instead of keeping the stored value, so an update should always send the complete binding.

  • conditions and options are only replaced when supplied. Omitting the conditions parameter and all option.* parameters keeps the stored values untouched.

  • To clear all conditions, send an empty conditions dict; to clear all options, send the clear_options flag.

Requires admin authentication and the policy action eventhandling_write.

JSON Parameters:

  • id – id of an existing binding to update; omit to create.

  • name – human-readable name of the binding (required).

  • event – comma-separated list of event names that should trigger this binding (required); see GET /event/available.

  • handlermodule – handler module identifier (required); see GET /event/handlermodules.

  • action – action the handler should perform (required); see GET /event/actions/(handlermodule).

  • position – post (default) or pre — when in the request lifecycle the handler fires.

  • ordering – integer >= 0; bindings with lower ordering run first. Default 0.

  • active – True (default) to enable the binding, False to create it disabled.

  • abort_on_error – False to keep the binding best-effort: if the handler raises, the failure is written to the audit log and the request continues without it. True aborts the request with an error instead. Set this for a handler whose result the request itself consumes, such as a response mangler that removes data from the response, or a federation handler that forwards the request to another privacyIDEA. If omitted, an existing binding keeps its current value and a new binding gets the default of its handler module, see GET /event/defaults/(handlermodule).

  • conditions – dict (or JSON-encoded dict) of per-binding conditions; see GET /event/conditions/(handlermodule). On update, replaces all conditions. Omit the parameter to keep the stored conditions untouched; send an empty dict to clear them.

  • clear_options – send True to clear all stored options when no option.* parameters are supplied (used to explicitly remove all options on update).

  • option.* – per-action options. Field names are taken after the option. prefix (e.g. option.subject becomes the subject option). On update, replaces all options. If no option.* parameter and no clear_options flag is supplied, the stored options are kept untouched.

Status Codes:

  • 200 OK – id of the binding in result.value.

POST /event/enable/(eventid)

Enable an event handler binding.

Requires admin authentication and the policy action eventhandling_write.

Parameters:

  • eventid – path component, the numeric id of the binding.

Status Codes:

  • 200 OK – id of the binding in result.value.

POST /event/disable/(eventid)

Disable an event handler binding. The binding is preserved but will not fire on its events until enabled again.

Requires admin authentication and the policy action eventhandling_write.

Parameters:

  • eventid – path component, the numeric id of the binding.

Status Codes:

  • 200 OK – id of the binding in result.value.

DELETE /event/(eid)

Delete the event handler binding with the given id.

Requires admin authentication and the policy action eventhandling_write.

Parameters:

  • eid – path component, the numeric id of the binding.

Status Codes:

  • 200 OK – id of the deleted binding in result.value.