Webhook post-processing

September 29, 2017 07:22

Overview

When "Job execution" or "Evaluation of policy set" is completed in Cloud Automator, the result can be received by POST request at any URL. The result will be sent in a JSON string. At that time, you can also authenticate by using Authorization header value.

Configuration item

Configuration item	Explanation	Restriction
Post-processing name	Enter post-process name.
Group	Select in which group the post-processing will be created. Only email post-processing is supported for group universal setting.
Service	Select the method to notify by post-processing. Please select Webhook.
Webhook URL (Required input)	You can enter any URL that starts with http:// or https://.	Up-to 2,048 letters
Authorization header (Optional)	You can enter any strings. When a value is entered, the POST request sent to the Webhook URL will be populated with a header like Authorization: the value entered. When a value is not entered, the Authorization header won't be populated in the POST request sent to the Webhook URL. When specifying the HTTP trigger job of Cloud Automator, enter the value beginning with CAAuth	Up-to 1,024 letters

How to setup

Open the "Add post process" menu from the post processing settings at the side menu.
Enter the following items in the basic information and webhook notification settings, and click Add.

Cautionary note for receiver of POST request

The URL entered as the webhook URL must work as follows.

Accept POST request with Content-Type header value of application/json
Return status code "2XX"
No need to return response body (it will ignore even you return response body)

When a status code other than 2XX is returned, it will be recorded in the job log or policy log at the Cloud Automator side that the execution of webhook post processing was failed.

When you need to verify whether the request is coming from Cloud Automator, you can determine if the value of the User-Agent header is Cloud Automator (Serverworks Co., Ltd.).

When the request from Cloud Automator to the webhook URL fails due to network problems, etc., it will try to send up to 10 times at regular intervals. If it continues to fail, then it will be recorded in the job log or policy log as a failure to execute Webhook post processing.

POST request content

The body of the POST request sent to the webhook URL will have following content.

When setting up for post-process of the job

[
  {
    "type": "job",
    "trigger_job_id": 10000,
    "trigger_job_log_id": 20000,
    "status": "completed",
    "name": "Job Name",
    "started_at": "2017-08-16T11:13:59Z",
    "finished_at": "2017-08-16T11:14:15Z"
  }
]

The value of each property is as follows.

Property	Type	Value
type	string	Always "job"
trigger_job_id	number	Job ID
trigger_job_log_id	number	Job log ID
status	string	Either "completed", "failed", or "aborted"
name	string	Job name
started_at	string	Job execution start date and time (UTC based on ISO8601)
finished_at	string	Job execution complete date and time (UTC based on ISO8601)

At the moment, the JSON contains only one execution result at any one time, but in the future the specification may change to include multiple results.

When setting up for post-process of the Policy

[
  {
    "type": "policy",
    "status": "completed",
    "policy_set_name": "Policy Set Name",
    "rule_name": "Policy Name",
    "evaluations_time": "2017-08-16T11:13:59Z",
    "evaluations": [
      {
        "ResourceId": "AWS Resource ID",
        "ResourceName": "AWS Resource Name",
        "ComplianceType": "COMPLIANT",
        "ResultDetailCode": null
      }
    ]
  }
]

The value of each property is as follows.

Property	Type	Value
type	string	Always "policy"
status	string	Either "completed" or "failed"
policy_set_name	string	Policy set name
rule_name	string	Evaluated policy name
evaluations_time	string	Policy evaluation date and time (UTC based on ISO8601)
evaluations	array of object	Evaluated AWS resource information

At the moment, the JSON contains only one execution result at any one time, but in the future the specification may change to include multiple results.

How to test Webhook post-processing

You can send a test request to the Webhook URL by clicking the "Send test request" button displayed on the created webhook post-processing details page and check the success or the failure.

The content of the request sent as a test will be as follows. (when it is set as post-processing of the job)

[
  {
    "type": "job",
    "trigger_job_id": 1,
    "trigger_job_log_id": 8,
    "status": "completed",
    "name": "Job for Test Request",
    "started_at": "2017-10-01T09:00:00Z",
    "finished_at": "2017-10-01T09:01:00Z",
  }
]