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/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 not partial. The full set of fields must be supplied on every update — action and position are silently set to empty strings if omitted, and options / conditions are deleted and replaced with whatever you send (so omitting them wipes them).

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.

  • conditions – dict (or JSON-encoded dict) of per-binding conditions; see GET /event/conditions/(handlermodule). On update, replaces all conditions.

  • 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.

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.