Event Listener Creation and Configuration¶

Learn about Events

Create an Event Listener¶

Creates a new listener in the server that will be notified of any events of the configured event types. Each listener must specify a notifier type to handle the event and any configuration necessary for that notifier type. An array of event types is also specified; the newly created listener is only notified when events of the given types are fired.

Method: POST
Path: /pulp/api/v2/events/
Permission: create
Request Body Contents: 

notifier_type_id (string) - one of the supported notifier type IDs
notifier_config (object) - configuration values the notifier will use when it handles an event
event_types (array) - array of event type IDs that this listener will handle. “*” matches all types

Response Codes:

201 - the event listener was successfully created
400 - if one of the required parameters is missing or an invalid event type is specified

Return: database representation of the created event listener, including its ID

Sample Request:

{
  "notifier_type_id" : "http",
  "notifier_config" : {
    "url" : "http://localhost/api"
  },
  "event_types" : ["repo.sync.finish", "repo.publish.finish"]
}

Sample 201 Response Body:

{
  "_href": "/pulp/api/v2/events/4ff708048a905b7016000008/",
  "_id": {"$oid": "4ff708048a905b7016000008"},
  "_ns": "event_listeners",
  "event_types": [
    "repo.sync.finish",
    "repo.publish.finish"
  ],
  "id": "4ff708048a905b7016000008",
  "notifier_config": {
    "url": "http://localhost/api"
  },
  "notifier_type_id": "http"
}

Retrieve All Event Listeners¶

Returns an array of all event listeners in the server.

Method: GET
Path: /pulp/api/v2/events/
Permission: read

Response Codes:

200 - array of event listeners, empty array if there are none

Return: database representation of each event listener

Sample 200 Response Body:

[
 {
   "_href": "/pulp/api/v2/events/4ff708048a905b7016000008/",
   "_id": {"$oid": "4ff708048a905b7016000008"},
   "_ns": "event_listeners",
   "event_types": [
     "repo.sync.finish",
     "repo.publish.finish"
   ],
   "id": "4ff708048a905b7016000008",
   "notifier_config": {
     "url": "http://localhost/api"
   },
   "notifier_type_id": "http"
 }
]

Retrieve a single Event Listener¶

Returns a single event listener from the server.

Method: GET
Path: /pulp/api/v2/events/<event_listener_id>/
Permission: read

Response Codes:

200 - the event listener detail
404 - if the given event listener does not exist

Return: database representation of the event listener

Sample 200 Response Body:

{
 "_href": "/pulp/api/v2/events/4ff708048a905b7016000008/",
 "_id": {"$oid": "4ff708048a905b7016000008"},
 "_ns": "event_listeners",
 "event_types": [
   "repo.sync.finish",
   "repo.publish.finish"
 ],
 "id": "4ff708048a905b7016000008",
 "notifier_config": {
   "url": "http://localhost/api"
 },
 "notifier_type_id": "http"
}

Delete an Event Listener¶

Deletes an event listener. The event listener is identified by its ID which is found either in the create response or in the data returned by listing all event listeners.

Method: DELETE
Path: /pulp/api/v2/events/<event_listener_id>/
Permission: delete

Response Codes:

200 - if the event listener was successfully deleted
404 - if the given event listener does not exist

Return: none

Update an Event Listener Configuration¶

Changes the configuration for an existing event listener. The notifier type cannot be changed. The event listener being updated is referenced by its ID which is found either in the create response or in the data returned by listing all event listeners.

If the notifier configuration is updated, the following rules apply:

Configuration keys that are not mentioned in the updated configuration remain unchanged.
Configuration keys with a value of none are removed entirely from the server-side storage of the notifier’s configuration.
Any configuration keys with non-none values are saved in the configuration, overwriting the previous value for the key if one existed.

Updating the event types is simpler; if present, the provided event types array becomes the new array of event types for the listener. The previous array is overwritten.

Method: PUT
Path: /pulp/api/v2/events/<event_listener_id>/
Permission: update
Request Body Contents: 

notifier_config (object) - (optional) dictates changes to the configuration as described above
event_types (array) - (optional) array of new event types for the listener to listen for. “*” matches all types.

Response Codes:

200 - if the listener was successfully updated
400 - if an invalid event type is specified
404 - if the given event listener does not exist

Return: database representation of the updated listener

Sample Request:

{
  "event_types" : ["repo.sync.start"]
}

Sample 200 Response Body:

{
  "_href": "/pulp/api/v2/events/4ff73d598a905b777d000014/",
  "_id": {"$oid": "4ff73d598a905b777d000014"},
  "_ns": "event_listeners",
  "event_types": ["repo.sync.start"],
  "id": "4ff73d598a905b777d000014",
  "notifier_config": {"url": "http://localhost/api"},
  "notifier_type_id": "http"
}