External synthetic API - POST external events to DESK

Pushes information about external synthetic events to DESK.

The request consumes an application/json payload.

POST	Managed https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/ext/events SaaS https://{your-environment-id}.live.dexp.ae/api/v1/synthetic/ext/events

Authentication

To execute this request, you need the Create and configure Synthetic monitors permission assigned to your API token. See the Authentication page to learn how to obtain and use it.

Parameters

Parameter	Type	Description	In	Required
ExternalSyntheticEvents	ExternalSyntheticEvents	The JSON body of the request, containing external synthetic events.	body	required

Request parameters JSON model

The ExternalSyntheticEvents object

The list of external synthetic events.

Element	Type	Description	Required
syntheticEngineName	string	The type of the external synthetic monitor.	optional
open	ExternalEventOpenNotification[]	The list of open external synthetic events.	optional
resolved	ExternalEventResolvedNotification[]	The list of closed external synthetic events.	optional

The ExternalEventResolvedNotification object

The closed external synthetic event.

Element	Type	Description	Required
testId	string	The ID of the Synthetic test.	optional
eventId	string	The unique ID of the event.	optional
endTimestamp	integer	The end timestamp of the event, in UTC milliseconds.	optional

The ExternalEventOpenNotification object

The open external synthetic event.

Element	Type	Description	Required
testId	string	The ID of the external synthetic monitor.	optional
eventId	string	The unique ID of the event.	optional
name	string	The name of the event.	optional
eventType	string	The type of the event. The eventType element can hold these values.	optional
reason	string	The cause of the event.	required
locationIds	string[]	The list of IDs of external synthetic locations where the event happens.	optional
startTimestamp	integer	The start timestamp of the event, in UTC milliseconds.	optional

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.

      
  {
  "syntheticEngineName": "string",
  "open": [
    {
      "testId": "string",
      "eventId": "string",
      "name": "string",
      "eventType": "testOutage",
      "reason": "string",
      "locationIds": [
        "string"
      ],
      "startTimestamp": 0
    }
  ],
  "resolved": [
    {
      "testId": "string",
      "eventId": "string",
      "endTimestamp": 0
    }
  ]
}

Possible values

Possible values for the eventType element in the ExternalEventOpenNotification object:

testOutage
testSlowdown

Response format

A successful request doesn't return any content.

Update an existing external monitor

To update an existing external monitor, specify its engine in the syntheticEngineName field of the ExternalSyntheticTests object and its ID in the id field of the ExternalSyntheticTest object.

You have to submit all the parameters of the monitor. Do not change the values of parameters you don't want to change.

Example

In this example, the request adds the outage event to the example of synthetic monitor - 1 external synthetic monitor from the POST external monitors to DESK example.

The API token is passed in the Authorization header.

You can download the request body JSON to perform a sample request in your environment. Be sure to replace the time stamps with recent ones or the results will be too old.

Curl

curl -X POST \
  https://mySampleEnv.live.dexp.ae/api/v1/synthetic/ext/events \
  -H 'Authorization: Api-Token abcdefjhij1234567890' \  
  -H 'Content-Type: application/json' \  
  -d '{
  "syntheticEngineName": "My external synthetic",
  "open": [
    {
      "testId": "externalSynteticMonitor1",
      "eventId": "extOpenEvent1-1",
      "name": "example of external monitor",
      "reason": "sample outage",
      "eventType": "testOutage",
      "locationIds": [
        "Linz1"
      ],
      "startTimestamp": 1543582285957
    }
  ],
  "resolved": [ ]
}
'

Request URL

https://mySampleEnv.live.dexp.ae/api/v1/synthetic/ext/events

Request body


        api-examples/synthetic/post-ext-event.json

Download

{
  "syntheticEngineName": "My external synthetic",
  "open": [
    {
      "testId": "externalSynteticMonitor1",
      "eventId": "extOpenEvent1-1",
      "name": "example of external event",
      "reason": "sample outage",
      "eventType": "testOutage",
      "locationIds": [
        "Linz1"
      ],
      "startTimestamp": 1543582285957
    }
  ],
  "resolved": [ ]
}

Response code

204

Result

The highlights show parameters submitted in the request.

External synthetic event