{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":512,"path":"api-reference/rest-apis/event_open-api.md","title":"Event Notification Management Open API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Event Notification Management Open API\n\nThe Event Notification Management Open API provides an endpoint to create, update, and delete events from the Events \\[em\\_event\\] table.\n\nThe Event Notification Management Open API \\(sn\\_ind\\_tmf688\\) is a ServiceNow implementation of the TM Forum Open API specification. This API is based on [TMF688 Event Management API User Guide v4.0.0](https://www.tmforum.org/resources/standard/tmf688-event-management-api-user-guide-v4-0-0/). You can locate additional alarm information in the [TMF642 Alarm Management API User Guide](https://projects.tmforum.org/wiki/download/attachments/134776981/TMF642_Alarm_Management_API_User_Guide_v4.0.0.pdf?api=v2).\n\nThis API can be extended to make customizations around required parameters, request body validation, additional REST operations, and field mappings. For more information, see the [Event Notification Management Open API Developer Guide](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/developer-guides/event-mgmt-notif_dev-guide.md).\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Event Notification Management Open API – POST instance\\_name/scope\\_id/GUID\n\nPlaces the payload of the associated request in the NowMQ queue. This queue is then processed in the background to create, update, and delete events within the Events \\[em\\_event\\] table.\n\nThis endpoint is different than other endpoints in the ServiceNow platform. Instead of having an endpoint for each specific task, such as create, update, and delete, there's only a single endpoint for all functionality. The parameter **eventType** in the call payload determines the task to perform based on its passed value of `AlarmCreateEvent`, `AlarmUpdateEvent`, or `AlarmDeleteEvent`.\n\nThe format of the REST call is also different than standard REST implementations. Each external system that will use this API, such as Kafka, database monitors, or other applications, must first register with the ServiceNow platform. They must also have their own webhook in place that uses the information provided during registration to generate the signature required to call this endpoint, including the `instance_name`, application `scope_id`, and unique `GUID`. The `GUID` identifies the external network system that the request came from.\n\nThe payload that you pass for this endpoint must correlate with the payload that is defined in the `TMFAlarmAPIConstants` script include for the corresponding **eventType** parameter value. Any parameters that are passed in the payload and not defined in the schema are ignored by the endpoint.\n\n- `AlarmCreateEvent`: `ALARM_CREATE_EVENT_SCHEMA`\n- `AlarmUpdateEvent`: `ALARM_CHANGE_EVENT_SCHEMA`\n- `AlarmDeleteEvent`: `ALARM_DELETE_EVENT_SCHEMA`\n\n### URL format\n\nDefault URL: `//`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nevent\n\n\n\nDetails about the event that occurred.Data type: Object\n\n```\n\"event\": {\n \"alarm\": {Object}\n}\n```\n\n
\n\nevent.alarm\n\n\n\nRequired when **eventType** is `AlarmCreateEvent`. Details about the associated alarm.\n\nData type: Object\n\n```\n\"alarm\": {\n \"affectedService\": [Array],\n \"alarmedObject\": {Object},\n \"alarmType\": \"String\",\n \"crossedThresholdInformation\": {Object},\n \"externalAlarmId\": \"String\",\n \"href\": \"String\",\n \"id\": \"String\",\n \"perceivedSeverity\": \"String\",\n \"probableCause\": \"String\",\n \"sourceSystemId\": \"String\",\n \"specificProblem\": \"String\",\n}\n```\n\n
\n\nevent.alarm.affectedService\n\n\n\nList of one or more services affected by the alarm.Data type: Array of Objects\n\n```\n\"affectedService\":[\n {\n \"href\": \"String\",\n \"id\": \"String\"\n },\n]\n```\n\n
\n\nevent.alarm.affectedService.href\n\n\n\nURL reference that provides details of the affected service.Data type: String\n\n
\n\nevent.alarm.affectedService.id\n\n\n\nIdentifier of the service affected by the alarm. This value maps to the affected configuration item \\(CI\\) on the alert.\n\nData type: String\n\n
\n\nevent.alarm.alarmedObject\n\n\n\nRequired when creating an event. Details of the alarm object.\n\nData type: Object\n\n```\n\"alarmedObject\":\n{\n \"href\": \"String\",\n \"id\": \"String\"\n}\n```\n\n
\n\nevent.alarm.alarmedObject.href\n\n\n\nRequired when creating an event. URL reference to get the details of the alarm object.\n\nData type: String\n\n
\n\nevent.alarm.alarmedObject.id\n\n\n\nRequired when **eventType** is `AlarmCreateEvent`. Unique identifier of the alarm object. This value maps to a CI in the system.\n\nData type: String\n\n
\n\nevent.alarm.alarmType\n\n\n\nRequired when **eventType** is `AlarmCreateEvent`. Type of alarm. Used to categorize the alarm.\n\nFor example: \"QualityOfServiceAlarm\"\n\nData type: String\n\n
\n\nevent.alarm.crossedThresholdInfomation\n\n\n\nDetails about the crossed threshold.Data type: Object\n\n```\n\"crossedThresholdInformation\":\n{\n \"thresholdId\": \"String\"\n}\n```\n\n
\n\nevent.alarm.crossedThresholdInfomation.thresholdId\n\n\n\nUnique identifier of the threshold that caused the alarm.\n\nData type: String\n\n
\n\nevent.alarm.externalAlarmId\n\n\n\nRequired when **eventType** is `AlarmCreateEvent`. Required when **eventType** is `AlarmDeleteEvent` or `AlarmChangeEvent` if the **Id** parameter is not specified. Unique identifier for the alarm from the source system posting the alarm.\n\nData type: String\n\n
\n\nevent.alarm.href\n\n\n\nURL reference to the alarm.For example: \"http://api/alarm/ROUTER\\_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00\"\n\nData type: String\n\n
\n\nevent.alarm.id\n\n\n\nRequired when **eventType** is `AlarmDeleteEvent` or `AlarmChangeEvent` if **externalAlarmId** is not specified. Unique identifier of the alarm. Specified by the alarm owning system.\n\nFor example: \"8675399\"\n\nData type: String\n\n
\n\nevent.alarm.perceivedSeverity\n\n\n\nRequired when **eventType** is `AlarmCreateEvent`. Possible severities associated with the alarm. The values are consistent with ITU-T Recommendation X.733. After an alarm has been cleared, its perceived severity is set to 'CLEAR' and can no longer be set.\n\nValid values:\n\n- CLEAR\n- CRITICAL\n- MAJOR\n- MINOR\n- WARNING\n\nData type: String\n\n
\n\nevent.alarm.probableCause\n\n\n\nRequired when **eventType** is `AlarmCreateEvent`.Most likely situation to trigger the alarm. Use with **alarmType** to qualify the alarm.\n\nThe possible values are consistent with ITU-T Recommendation X.733 or 3GPP TS 32.111-2 Annex B.\n\nFor example: \"Threshold crossed\"\n\nData type: String\n\n
\n\nevent.alarm.sourceSystemId\n\n\n\nRequired when **eventType** is `AlarmCreateEvent`. Unique identifier of the source system of the alarm.\n\nFor example: \"SOURCE\\_SYSTEM\\_vManage\\_00000\\_000\\_00\"\n\nData type: String\n\n
\n\nevent.alarm.specificProblem\n\n\n\nSpecific problem that triggers the alarm. Use with the **probableCause** tparameter o qualify the alarm.For example: \"Inbound Traffic threshold crossed\"\n\nData type: String\n\n
\n\neventType\n\n\n\nRequired. Type of event to process.Valid values:\n\n- AlarmChangeNotification\n- AlarmCreateNotification\n- AlarmDeleteNotification\n\nData type: String\n\n
### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Header|Description|\n|------|-----------|\n|Accept|Data format of the response body. Only supports **application/json**.|\n\n|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Returned for every call regardless of the actual processing status of the call. Only indicates that the endpoint received the request.|\n\n### Response body parameters\n\n|Name|Description|\n|----|-----------|\n|None|This endpoint is asynchronous and therefore doesn't return any response data.|\n\n### cURL request\n\nThe following shows the possible payload for a create alarm event. This example reflects the parameters that are in the default implementation \\(`AlarmCreateEventSchema`\\).\n\n```\n\n--data \"{\n \"eventType\": \"AlarmCreateNotification\",\n \"event\": {\n \"alarm\": {\n \"id\": \"\",\n \"externalAlarmId\": \"ext123456\",\n \"alarmType\": \"QualityOfServiceAlarm\",\n \"perceivedSeverity\": \"MINOR\",\n \"alarmedObject\": {\n \"id\": \"vManage_000000\",\n \"href\": \" http://api/alarmedobject/000000\"\n },\n \"probableCause\": \"Threshold crossed\",\n \"sourceSystemId\": \"SOURCE_SYSTEM_vManage_00000_000_00\",\n \"href\": \"http://api/alarm/ROUTER_IF@Cisco-0000-0-0-0-0-00-00-0-- Xz0/00@00\",\n \"specificProblem\": \"Inbound Traffic threshold crossed\",\n \"crossedThresholdInformation\": {\n \"thresholdId\": \"12fasdfasdfasd\"\n },\n \"affectedService\": [\n {\n \"id\": \"SD WAN Enterprise Solutions\",\n \"href\": \"http://api/service/vlan_dot0_dot0\"\n }\n ]\n }\n }\n}\n```\n\nNo response returned.\n\n### cURL request\n\nThe following shows the possible payload for a change alarm event. This example reflects the parameters that are in the default implementation \\(`AlarmChangeEventSchema`\\).\n\n```\n\n--data \"{\n \"eventType\": \"AlarmChangeEventSchema\",\n \"event\": {\n \"alarm\": {\n \"id\": \"\",\n \"externalAlarmId\": \"ext123456\",\n \"perceivedSeverity\": \"MAJOR\",\n \"probableCause\": \"Threshold crossed\",\n \"crossedThresholdInformation\": {\n \"thresholdId\": \"12fasdfasdfasd\"\n },\n \"affectedService\": [\n {\n \"id\": \"SD WAN Enterprise Solutions\",\n \"href\": \"http://api/service/vlan_dot0_dot0\"\n }\n ]\n }\n }\n}\n\n```\n\nNo response returned.\n\n### cURL request\n\nThe following shows the possible payload for a delete \\(clear\\) alarm event. This example reflects the parameters that are in the default implementation \\(`AlarmDeleteEventSchema`\\).\n\n```\n\n--data \"{\n \"eventType\": \"AlarmDeleteEventSchema\",\n \"event\": {\n \"alarm\": {\n \"id\": \"\",\n \"externalAlarmId\": \"ext123456\",\n \"perceivedSeverity\": \"MAJOR\",\n \"probableCause\": \"Threshold crossed\",\n \"crossedThresholdInformation\": {\n \"thresholdId\": \"12fasdfasdfasd\"\n }\n }\n }\n}\n```\n\nNo response returned.\n\n"}}