# The Redfish Event Service

Redfish standardizes an event subscription service that enables monitoring
applications to receive notifications when the REST data changes or when
certain alerts occur. These notifications are HTTPS POST operations sent
to a listener URL of your choice.

The `EventService` resource type is located in the Redfish data model at
`/redfish/v1/EventService/`. This resource includes a link to the collection
of subscriptions referred as `EventDestinationCollection` and located at the
`/redfish/v1/EventService/Subscriptions`
 URI .

### Event subscription

In order to receive events, you must identify the URL of an HTTPS server
accepting POST requests and accessible to the [BMC](/docs/etc/glossaryterms)
management network. Event POST operations generated by the BMC will be sent to
this event listener URL after successful subscription.

TIP
If needed, The DMTF provides a Redfish Event Listener on
GitHub.

To subscribe to an event, you need to construct a JSON object and POST it to
the `EventDestinationCollection`
 URI 
of the managed BMC. Upon success, you receive an HTTP 201 Created response and
a new subscription has been added in the collection.

NOTE
Most of the BMC Redfish event services (including iLO and OpenBMC) does not
test the event listener destination URL during the subscription phase. It is
your responsibility to verify that the BMC can post HTTPS requests in the
listener destination.

The following example creates an event subscription in an iLO 6,
with the `Destination` and `Context` properties as the only properties part of
the request body. If not provided, the default value for `EventFormatType`
is set to `Event`. Use the `MetricReport` value when subscribing to
[metric reports](/docs/concepts/redfishtelemetry).

Generic event subscription request

```text
POST /redfish/v1/EventService/Subscriptions/
```

Request body

```json
{
    "Destination": "https://{{EventListener}}/path/to/listener.app",
    "Context": "Some context"
}
```

Response body

```json
{
    "error": {
        "code": "iLO.0.10.ExtendedInfo",
        "message": "See @Message.ExtendedInfo for more information.",
        "@Message.ExtendedInfo": [
            {
                "MessageId": "Base.1.17.Created"
            }
        ]
    }
}
```

NOTE
If the creation request does not provide any value for the `RegistryPrefixes`
and the `Oem` resources, the Redfish service may fill them up with default
values. This is the case for HPE iLO 6; the previous example does not provide
any detail concerning the subscription but `RegisryPrefixes` and `Oem/Hpe`
objects have been automatically supplied by the service. Refer to the
response body of the following example.

Once the subscription is created, its URI appears in the
`EventDestinationCollection` collection. The following example retrieves the
subscription entry created by the previous example.

Generic request

```text
GET /redfish/v1/EventService/Subscriptions/{item}/
```

Body Response

```json
{
    "@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination",
    "@odata.etag": "W/\"F8B2DF36\"",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/2/",
    "@odata.type": "#EventDestination.v1_13_0.EventDestination",
    "Id": "2",
    "Context": "Some context",
    "Description": "iLO Event Subscription",
    "Destination": "https://10.124.107.98/path/to/listener.app",
    "EventFormatType": "Event",
    "HttpHeaders": [],
    "MetricReportDefinitions": [],
    "Name": "Event Subscription",
    "Oem": {
        "Hpe": {
            "@odata.context": "/redfish/v1/$metadata#HpeEventDestination.HpeEventDestination",
            "@odata.type": "#HpeEventDestination.v2_1_0.HpeEventDestination",
            "DeliveryRetryAttempts": 3,
            "DeliveryRetryIntervalInSeconds": 30,
            "MutualAuthenticationEnabled": false,
            "RequestedMaxEventsToQueue": 3,
            "RetireOldEventInMinutes": 10
        }
    },
    "Protocol": "Redfish",
    "RegistryPrefixes": [
        "NetworkDevice",
        "StorageDevice",
        "ResourceEvent",
        "iLOEvents",
        "iLOResourceEvents"
    ],
    "SubscriptionType": "RedfishEvent"
}
```

The `RegistryPrefixes`
 property 
is a list of message registry prefixes to subscribe to. They correspond to the
prefix of the
 error messages 
of the form `<RegistryPrefix>.<MajorVersion>.<MinorVersion>.<MessageKey>`.

If you subscribe to the the `StorageDevice` registry prefix, the destination
event listener will receive all the error messages starting with
 StorageDevice .
Refer to the [Event interpretation](#event-interpretation)
paragraph for more information.

The following example retrieves the list of possible RegistryPrefixes
from an HPE iLO 6.

Generic GET request

```text
GET /redfish/v1/EventService/?$select=RegistryPrefixes
```

iLOrest

```shell
ilorest login <ilo-ip> -u <ilo-user> -p password
ilorest get RegistryPrefixes --json --selector EventService.
ilorest logout
```

Body response

```json
{
    "@odata.context": "/redfish/v1/$metadata#EventService.EventService",
    "@odata.etag": "W/\"3015330F\"",
    "@odata.id": "/redfish/v1/EventService/",
    "@odata.type": "#EventService.v1_7_2.EventService",
    "RegistryPrefixes": [
        "iLOEvents",
        "ResourceEvent",
        "NetworkDevice",
        "StorageDevice",
        "iLOResourceEvents"
    ]
}
```

The following example retrieves the list of event subscriptions
from an HPE iLO 6.

Generic request

```text
GET /redfish/v1/EventService/Subscriptions/
```

Body response

```json
{
    "@odata.context": "/redfish/v1/$metadata#EventDestinationCollection.EventDestinationCollection",
    "@odata.etag": "W/\"AA6D42B0\"",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/",
    "@odata.type": "#EventDestinationCollection.EventDestinationCollection",
    "Description": "iLO User Event Subscriptions",
    "Name": "EventSubscriptions",
    "Members": [
        {
            "@odata.id": "/redfish/v1/EventService/Subscriptions/6/"
        }
    ],
    "Members@odata.count": 1
}
```

The following example shows an event subscription with specific `HttpHeaders`
and `Context`  properties. The `HttpHeaders` property contains a list of HTTP
headers that the Redfish service will use when sending events to the event
listener. This property could be used to perform an authentication in the
event listener.

NOTE
The Redfish specification
advises to return an empty `HttpHeaders` array upon GET requests of
subscription details. Refer to the Subscription detail tabulation
of the following example.

The `Context` property is a string that will be part of the event sent to the
listener. With this information the listener could dispatch the event to a
specific service able to act accordingly.

Generic request

```text
POST /redfish/v1/EventService/Subscriptions/
```

Subscription request body

```json
{
    "Destination": "https://{{EventListener}}/",
    "Context": "Some context",
    "RegistryPrefixes": [
        "StorageDevice",
        "NetworkDevice",
        "iLOEvents",
        "ResourceEvent"
    ],
    "HttpHeaders":{
        "Header1": "HeaderValue1",
        "Header2": "HeaderValue2"
    }
}
```

Subscription detail

```json
{
    "@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination",
    "@odata.etag": "W/\"71734713\"",
    "@odata.id": "/redfish/v1/EventService/Subscriptions/3/",
    "@odata.type": "#EventDestination.v1_13_0.EventDestination",
    "Id": "3",
    "Context": "Some context",
    "Description": "iLO Event Subscription",
    "Destination": "https://192.168.1.46/",
    "EventFormatType": "Event",
    "HttpHeaders": [],
    "MetricReportDefinitions": [],
    "Name": "Event Subscription",
    "Oem": {
        "Hpe": {
            "@odata.context": "/redfish/v1/$metadata#HpeEventDestination.HpeEventDestination",
            "@odata.type": "#HpeEventDestination.v2_1_0.HpeEventDestination",
            "DeliveryRetryAttempts": 3,
            "DeliveryRetryIntervalInSeconds": 30,
            "MutualAuthenticationEnabled": false,
            "RequestedMaxEventsToQueue": 3,
            "RetireOldEventInMinutes": 10
        }
    },
    "Protocol": "Redfish",
    "RegistryPrefixes": [
        "StorageDevice",
        "NetworkDevice",
        "iLOEvents",
        "ResourceEvent"
    ],
    "SubscriptionType": "RedfishEvent"
}
```

TIP
More event examples are presented in the HPE
[iLO specific supplement documents](/docs/redfishservices/ilos/supplementdocuments/iloeventservices/).

## Testing the Event service

The Redfish Event Service offers the possibility to trigger test events
from managed BMCs. The following test event,
with `MessageId` containing `iLOResourceEvents`, will be forwarded to
all the subscription destinations having `iLOResourceEvents`
in its `RegistryPrefixes` list. Refer to the
[next paragraph](#event-interpretation) for the interpretation of this event.

Generirc POST test event

```text
POST /redfish/v1/EventService/Actions/EventService.SubmitTestEvent
```

Test event body

```json
{
  "EventID": "myEventId",
  "EventTimestamp": "2023-02-13T14:49:20Z",
  "Severity": "Warning",
  "Message": "This is a test event message",
  "MessageId": "iLOResourceEvents.1.3.DrvArrLogDrvErasing",
  "MessageArgs": [ "1", "slot 3" ],
  "OriginOfCondition": "/redfish/v1/Systems/1/Storage"
}
```

Response body

```json
{
    "error": {
        "code": "iLO.0.10.ExtendedInfo",
        "message": "See @Message.ExtendedInfo for more information.",
        "@Message.ExtendedInfo": [
            {
                "MessageId": "Base.1.12.Success"
            }
        ]
    }
}
```

## Event interpretation

When an event occurs in a server, a `MessageId` property is associated to it.
Its value is a message reference
(i.e. `iLOResourceEvents.x.y.DrvArrLogDrvErasing`) described in the
 message registry .
Only event destinations containing the message registry prefix of the
`MessageId` property are notified. Upon reception, they can consult the related
message registry file to get more detail and optionally resolution actions.

TIP
Registry file
 URIs 
are listed in the `MessageRegistryFileCollection` collection at
`/redfish/v1/Registries`.

Upon reception of an event, the event listener can use the prefix of the
`MessageId` property to retrieve the URI of the corresponding message registry
URI. In the test event example above, the message registry prefix contained in
the `MessageId` property is `iLOResourceEvents`. A GET of
`/redfish/v1/registries/iLOResourceEvents` leads to
`/redfish/v1/RegistryStore/registries/en/iLOResourceEvents.json`.
A GET of this URI retrieves the entire message registry. This file contains
an entry for the `DrvArrLogDrvErasing`
 error message .

Refer to the [Error responses](/docs/concepts/errorresponses/)
section for more information on this subject.