The webhooks API

This overview of the XProtect webhooks API is based on the Webhooks API, version 1.0.

The HTTP POST object consists of a header and the body (payload).

HTTP POST Body (version 1.0)

The payload of the HTTP POST is an application/json object with the following keys:

Key Type Description
Event BaseEvent (serialized to JSON) The event that triggered the rule.
Site
Copy 
{
 ServerHostName: string,
 
AbsoluteUri: string,

 
 ServerType: string,
}

Information about the system where this event originated.

Use this field when using the same webhook endpoint for multiple XProtect installations.

 

Copy 
{
   "Event": {
       "EventHeader": {
           "ID": "2388f93d-5cb0-48e0-9524-d8bb981e1629",
           "Timestamp": "2022-11-26T15:59:39.2988877Z",
           "Type": "System Event",
           "Version": "1.0",
           "Priority": 1,
           "PriorityName": "High",
           "Name": "External Event",
           "Message": "External Event",
           "Source": {
               "Name": "Event High",
               "FQID": {
                   "ServerId": {
                       "Type": "XPCO",
                       "Hostname": "ec2amaz-111k11j",
                       "Port": 80,
                       "Id": "2f04e7ee-2ee2-49d4-8415-de28dba7ef2e",
                       "Scheme": "http"
                   },
                   "ParentId": "2f04e7ee-2ee2-49d4-8415-de28dba7ef2e",
                   "ObjectId": "13860010-ded3-42ff-a2a9-cc6ba4a49636",
                   "FolderType": 0,
                   "Kind": "c9bdac3f-41dc-4afa-b057-61767a3914b7"
                }
           },
           "MessageId": "0fcb1955-0e80-4fd4-a78a-db47ee89700c"
       }
   },
   "Site": {
       "ServerHostname": "ec2amaz-111k11j",
       "AbsoluteUri": "http://ec2amaz-111k22j/",
       "ServerType": "XPCO"
   }
}

HTTP POST Headers

The HTTP POST  headers contains the following keys:

Key Type Description
X-Milestone-Api-Version String The version of the body. “v1.0” is currently the only supported version.
X-Hub-Signature-256 String

The HMAC hex digest using SHA-256 of the body.

The value always starts with “sha256=”.

For more information, see “Improving webhook security with tokens”.

Copy 
{
   "X-Hub-Signature-256": "sha256=LBr6+XIEOZKgMck2/aG1CNCaCCOAwHT4o+vYRE4D3JM=",
   "X-Milestone-Api-Version": "v1.0",
   "content-type": "application/json; charset=utf-8"
}

Failed requests and retry policy

If the POST requests fails with a 400 error, it is not retried again.

If the POST requests fails with any other status code, or a timeout, the request will be retried 2 more times, with each attempt spaced 30 seconds apart.

The same "Event.EventHeader.ID from the original HTTP POST Body will be used in all retries so the subscribing/receiving service can track any potential duplicate event notifications.