chore(sync): update sync documentation to include event mirroring

content/reference/api/scm/sync.md

@@ -27,6 +27,18 @@ The following parameters are used to configure the endpoint:
 | `200`       | indicates the request has succeeded                 |
 | `401`       | indicates the user does not have proper permissions |
 
+## Description
+
+The sync endpoint allows users to re-align their repository in Vela with its SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. 
+
+Further, as of `v0.19.0`, the sync endpoint can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like
+
+```sh
+"unable to process webhook: <org>/<repo> does not have comment events enabled"
+```
+
+hitting the sync endpoint should re-configure the SCM webhook to only send events that are allowed. Once aligned, you should not have to hit this endpoint again, even if the subscribed events are changed.
+
 ## Sample
 
 {{% alert color="warning" %}}

content/reference/api/scm/syncAll.md

@@ -26,6 +26,18 @@ The following parameters are used to configure the endpoint:
 | `200`       | indicates the request has succeeded                 |
 | `401`       | indicates the user does not have proper permissions |
 
+## Description
+
+The sync-all endpoint allows users to re-align their organization's repositories in Vela with their SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. 
+
+Further, as of `v0.19.0`, the sync-all endpoint can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like
+
+```sh
+"unable to process webhook: <org>/<repo> does not have comment events enabled"
+```
+
+hitting the sync-all endpoint should re-configure the SCM webhook for all repos in the organization to only send events that are allowed. Once aligned, you should not have to hit this endpoint again, even if the subscribed events are changed.
+
 ## Sample
 
 {{% alert color="warning" %}}

content/reference/cli/repo/sync.md

@@ -34,6 +34,18 @@ This command also supports setting the following parameters via a configuration
 For more information, please review the [CLI config documentation](/docs/reference/cli/config/).
 {{% /alert %}}
 
+## Description
+
+The sync command allows users to re-align their repository in Vela with its SCM mirror. This discrepancy can come in the form of a repository that has been deleted from the SCM but not in Vela. 
+
+Further, as of `v0.19.0`, the sync command can be used to adjust events that are sent to Vela from the SCM that the Vela-instance of the repo is not subscribed to. For example, if your audit page has errors like
+
+```sh
+"unable to process webhook: <org>/<repo> does not have comment events enabled"
+```
+
+running the sync command should re-configure the SCM webhook to only send events that are allowed. Once aligned, you should not have to run this command again, even if the subscribed events are changed.
+
 ## Samples
 
 {{% alert color="warning" %}}