Add webhook API documentation (#215)

docs/artifact_repositories/about.md

@@ -39,6 +39,12 @@ registries:
 | NPM | [Documentation][NPM] |
 | Cargo | [Documentation][Cargo] |
 
+### Notification API
+
+Phylum supports sending out notifications whenever a package fails analysis. To
+receive those notifications, you can [setup webhooks].
+
+[setup webhooks]: ./api.md#webhooks
 [Artifactory]: ./artifactory.md
 [PyPI]: ./pypi.md
 [NPM]: ./npm.md

docs/artifact_repositories/api.md

@@ -0,0 +1,57 @@
+# API
+
+This section documents the public API for Phylum's artifact repository offering.
+
+## Webhooks
+
+Webhooks will send out notifications whenever a package that was accessed
+through a repository proxy fails analysis.
+
+To setup a new webhook, you can use the following curl command:
+
+```sh
+# Phylum group used with the registry proxy.
+export PHYLUM_GROUP=…
+# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
+export PHYLUM_API_KEY=…
+# URL which will be called on analysis failure.
+export WEBHOOK_URL=…
+# Shared secret used to validate authenticity of webhook callbacks
+export SECRET=…
+
+curl \
+    -X PUT \
+    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
+    --json "{\"url\": \"$WEBHOOK_URL\", \"secret\": \"$SECRET\"}" \
+    "https://aviary.phylum.io/webhooks"
+```
+
+Once a webhook is registered, policy violations will be sent to it in the same
+format as the [package check endpoint].
+
+Since these reports contain security advisories, it's important to make sure
+that they were generated by Phylum and the endpoint wasn't called by a third
+party. To make this possible, all official webhook notification calls will
+include a `sha256` query parameter which contains a hexadecimal representation
+of the SHA256-HMAC of the response body, generated with the shared secret
+provided when registering the webhook.
+
+### Deleting Webhooks
+
+If a webhook is no longer in use, it should be deleted:
+
+```sh
+# Phylum group used with the registry proxy.
+export PHYLUM_GROUP=…
+# https://docs.phylum.io/knowledge_base/api-keys#generate-an-api-key
+export PHYLUM_API_KEY=…
+# URL-encoded URL used during webhook setup.
+export WEBHOOK_URL=…
+
+curl \
+    -X DELETE \
+    --user "$PHYLUM_GROUP:$PHYLUM_API_KEY" \
+    "https://aviary.phylum.io/webhooks/$WEBHOOK_URL"
+```
+
+[package check endpoint]: https://api.phylum.io/api/v0/swagger/index.html#/Organizations/organizations_group_packages_check

site/sidebars.js

@@ -132,6 +132,7 @@ const sidebars = {
         'artifact_repositories/pypi',
         'artifact_repositories/npm',
         'artifact_repositories/cargo',
+        'artifact_repositories/api',
       ],
     },
     {