Merge pull request #11898 from mmpei/offical-webhook-user-guide

Update webhook user guide

docs/working-with-projects/project-configuration/configure-webhooks.md

@@ -9,54 +9,87 @@ The action that is taken upon receiving a notification from a Harbor project dep
 
 ### Supported Events
 
-You can define one webhook endpoint per project. Webhook notifications provide information about events in JSON format and are delivered by `HTTP` or `HTTPS POST` to an existing webhhook endpoint URL that you provide. The following table describes the events that trigger notifications and the contents of each notification.
+You can define multiple webhook endpoints per project. Harbor supports two kinds of endpoints currently,  `HTTP`  and `SLACK`. Webhook notifications provide information about events in JSON format and are delivered by `HTTP` or `HTTPS POST` to an existing webhhook endpoint URL or Slack address that you provide. The following table describes the events that trigger notifications and the contents of each notification.
 
 |Event|Webhook Event Type|Contents of Notification|
 |---|---|---|
-|Push image to registry|`IMAGE PUSH`|Repository namespace name, repository name, resource URL, tags, manifest digest, image name, push time timestamp, username of user who pushed image|
-|Pull manifest from registry|`IMAGE PULL`|Repository namespace name, repository name, manifest digest, image name, pull time timestamp, username of user who pulled image|
-|Delete manifest from registry|`IMAGE DELETE`|Repository namespace name, repository name, manifest digest, image name, image size, delete time timestamp, username of user who deleted image|
-|Upload Helm chart to registry|`CHART PUSH`|Repository name, chart name, chart type, chart version, chart size, tag, timestamp of push, username of user who uploaded chart|
-|Download Helm chart from registry|`CHART PULL`|Repository name, chart name, chart type, chart version, chart size, tag, timestamp of push, username of user who pulled chart|
-|Delete Helm chart from registry|`CHART DELETE`|Repository name, chart name, chart type, chart version, chart size, tag, timestamp of delete, username of user who deleted chart|
-|Image scan completed|`IMAGE SCAN COMPLETED`|Repository namespace name, repository name, tag scanned, image name, number of critical issues, number of major issues, number of minor issues, last scan status, scan completion time timestamp, vulnerability information (CVE ID, description, link to CVE, criticality, URL for any fix), username of user who performed scan|
-|Image scan failed|`IMAGE SCAN FAILED`|Repository namespace name, repository name, tag scanned, image name, error that occurred, username of user who performed scan|
-|Project quota exceeded|`PROJECT QUOTA EXCEED`|Repository namespace name, repository name, tags, manifest digest, image name, push time timestamp, username of user who pushed image|
+|Push artifact to registry|`PUSH_ARTIFACT`|Repository namespace name, repository name, resource URL, tags, manifest digest, artifact name, push time timestamp, username of user who pushed artifact|
+|Pull artifact from registry|`PULL_ARTIFACT`|Repository namespace name, repository name, manifest digest, artifact name, pull time timestamp, username of user who pulled artifact|
+|Delete artifact from registry|`DELETE_ARTIFACT`|Repository namespace name, repository name, manifest digest, artifact name, artifact size, delete time timestamp, username of user who deleted image|
+|Upload Helm chart to chartMuseum|`UPLOAD_CHART`|Repository name, chart name, chart type, chart version, chart size, tag, timestamp of push, username of user who uploaded chart|
+|Download Helm chart from chartMuseum|`DOWNLOAD_CHART`|Repository name, chart name, chart type, chart version, chart size, tag, timestamp of push, username of user who pulled chart|
+|Delete Helm chart from chartMuseum|`DELETE_CHART`|Repository name, chart name, chart type, chart version, chart size, tag, timestamp of delete, username of user who deleted chart|
+|Image scan completed|`SCANNING_COMPLETED`|Repository namespace name, repository name, tag scanned, image name, number of critical issues, number of major issues, number of minor issues, last scan status, scan completion time timestamp, vulnerability information (CVE ID, description, link to CVE, criticality, URL for any fix), username of user who performed scan|
+|Image scan failed|`SCANNING_FAILED`|Repository namespace name, repository name, tag scanned, image name, error that occurred, username of user who performed scan|
+|Project quota exceeded|`QUOTA_EXCEED`|Repository namespace name, repository name, tags, manifest digest, artifact name, push time timestamp, username of user who pushed artifact|
+|Project quota near threshold|`QUOTA_WARNING`|Repository namespace name, repository name, tags, manifest digest, artifact name, push time timestamp, username of user who pushed artifact|
+|Artifact replication finished|`REPLICATION`|Repository namespace name, repository name, tags, manifest digest, artifact name, push time timestamp, username of user who trigger the replication|
 
-#### JSON Payload Format
+#### Payload Format
 
-The webhook notification is delivered in JSON format. The following example shows the JSON notification for a push image event:
+The webhook notification is delivered in JSON format. The following example shows the JSON notification for a push artifact event when using `HTTP` kind endpoint:
 
 ```json
 {
-  "event_type": "pushImage",
-  "events": [
-    {
-      "project": "prj",
-      "repo_name": "repo1",
-      "tag": "latest",
-      "full_name": "prj/repo1",
-      "trigger_time": 158322233213,
-      "image_id": "9e2c9d5f44efbb6ee83aecd17a120c513047d289d142ec5738c9f02f9b24ad07",
-      "project_type": "Private"
+	"type": "PUSH_ARTIFACT",
+	"occur_at": 1586922308,
+	"operator": "admin",
+	"event_data": {
+		"resources": [{
+			"digest": "sha256:8a9e9863dbb6e10edb5adfe917c00da84e1700fa76e7ed02476aa6e6fb8ee0d8",
+			"tag": "latest",
+			"resource_url": "hub.harbor.com/test-webhook/debian:latest"
+		}],
+		"repository": {
+			"date_created": 1586922308,
+			"name": "debian",
+			"namespace": "test-webhook",
+			"repo_full_name": "test-webhook/debian",
+			"repo_type": "private"
+		}
+	}
+}
+```
+when you select the Slack type, and fill a Slack incoming webhook URL as endpoint, the message you received in Slack will be like,
+```json
+Harbor webhook events
+event_type: PUSH_ARTIFACT
+occur_at: April 15th at 11:59 AM
+operator: admin
+event_data:
+{
+    "resources": [
+        {
+            "digest": "sha256:8a9e9863dbb6e10edb5adfe917c00da84e1700fa76e7ed02476aa6e6fb8ee0d8",
+            "tag": "latest",
+            "resource_url": "hub.harbor.com/test-webhook/debian:latest"
+        }
+    ],
+    "repository": {
+        "date_created": 1586922308,
+        "name": "debian",
+        "namespace": "test-webhook",
+        "repo_full_name": "test-webhook/debian",
+        "repo_type": "private"
     }
-  ]
 }
 ```
 
 ### Webhook Endpoint Recommendations
 
-The endpoint that receives the webhook should ideally have a webhook listener that is capable of interpreting the payload and acting upon the information it contains. For example, running a shell script.
+There are two kinds of endpoints.  For `HTTP` the endpoint that receives the webhook should ideally have a webhook listener that is capable of interpreting the payload and acting upon the information it contains. For example, running a shell script.
+
+And for Slack endpoint, you should follow the [guide of Slack incoming webhook](https://api.slack.com/messaging/webhooks).
 
 ### Example Use Cases
 
 You can configure your continuous integration and development infrastructure so that it performs the following types of operations when it receives a webhook notification from Harbor.
 
-- Image push: 
+- Artifact push: 
   - Trigger a new build immediately following a push on selected repositories or tags.
-  - Notify services or applications that use the image that a new image is available and pull it.
-  - Scan the image using Clair.
-  - Replicate the image to remote registries.
+  - Notify services or applications that use the artifact that a new artifact is available and pull it.
+  - Scan the artifact using Clair.
+  - Replicate the artifact to remote registries.
 - Image scanning:
   - If a vulnerability is found, rescan the image or replicate it to another registry.
   - If the scan passes, deploy the image.
@@ -64,24 +97,30 @@ You can configure your continuous integration and development infrastructure so
 ### Configure Webhooks
 
 1. Log in to the Harbor interface with an account that has at least project administrator privileges.
+
 1. Go to **Projects**, select a project, and select **Webhooks**.
 
     ![Webhooks option](../../../img/webhooks1.png)
 
+1. Select notify type `HTTP`, so the webhook will be send to a HTTP endpoint.
+
+1. Select events that you want to subscribe.
+
 1. Enter the URL for your webhook endpoint listener.
+
 1. If your webhook listener implements authentication, enter the authentication header. 
+
 1. To implement `HTTPS POST` instead of `HTTP POST`, select the **Verifiy Remote Certficate** check box.
 
     ![Webhook URL](../../../img/webhooks2.png)
 
 1. Click **Test Endpoint** to make sure that Harbor can connect to the listener.
+
 1. Click **Continue** to create the webhook.
 
-When you have created the webhook, you see the status of the different notifications and the timestamp of the last time each notification was triggered. You can click **Disable** to disable notifications. 
+When you have created the webhook, you can click on the arrow at the left end to see the status of the different notifications and the  timestamp of the last time each notification was triggered. You can also manage the webhook by clicking the drop list button of `ACTION...` . 
 
-{{< note >}}
-You can only disable and reenable all notifications. You cannot disable and enable selected notifications.
-{{< /note >}}
+You can modify the webhook, you can also `Enable` or `Disable` the webhook.
 
 ![Webhook Status](../../../img/webhooks3.png)