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"
}