Merge pull request mendix#5962 from mendix/lz-webhook-api

Webhooks API

Author: Luyao-Zhang-1

content/en/docs/apidocs-mxsdk/apidocs/webhooks-api.md

@@ -0,0 +1,98 @@
+---
+title: "Webhooks API"
+url: /apidocs-mxsdk/apidocs/webhooks-api/
+type: swagger
+category: "API Documentation"
+weight: 97
+tags: ["API", "webhooks", "Mendix Cloud"]
+---
+
+{{% alert color="warning" %}} This feature is in Beta. For more information on Beta products, see [Beta Releases](/releasenotes/beta-features/). {{% /alert %}}
+
+## 1 Introduction
+
+The Mendix Webhooks API allows you to manage [webhooks](/developerportal/deploy/webhooks/).
+
+You can use the API to do the following:
+
+* List all webhooks
+* Get a webhook
+* Create a webhook
+* Update a webhook
+* Delete a webhook
+
+## 2 Authentication{#authentication}
+
+Authentication for the Webhooks API uses a personal access token (PAT).
+
+### 2.1 Generating a PAT
+
+To generate a PAT, see the [Personal Access Tokens](/developerportal/community-tools/mendix-profile/#pat) section in *Mendix Profile*.
+
+Select the following as scopes:
+
+* `mx:webhook:read` – to perform `GET` operations
+* `mx:webhook:write` – to perform all operations (`GET`, `POST`, `PUT`, and `DELETE`)
+
+Store the generated value `{GENERATED_PAT}` somewhere safe so you can use it to authorize your Mendix Cloud Webhooks API calls.
+
+### 2.2 Using the PAT
+
+Each request must contain an `Authorization` header with the value `MxToken {GENERATED_PAT}`. For example:
+
+```http {linenos=false}
+GET /apps/80a28d6e-c5fc-43d9-87c2-d7d56b07542/webhooks HTTP/1.1
+Authorization: MxToken 7LJE…vk
+```
+
+To authenticate calls when using the Open API specification below, click **Authorize** and use the value `MxToken {GENERATED_PAT}`.
+
+## 3 Examples
+
+### 3.1 Using the API to Create and Update a Webhook Endpoint
+
+The following procedure will create a webhook endpoint and update the webhook endpoint:
+
+1. Set up your authentication PAT.
+
+2. To create a wehhook for an app, call `POST /apps/{app-id}/webhooks`. For example:
+
+   ```http {linenos=false}
+   POST /apps/80a28d6e-c5fc-43d9-87c2-d7d56b07542e/webhooks
+   ```
+
+   The API call returns `id`, `name`, `url`, `eventTypes`, `isActive`, `validationSecret` and `headers` of the new webhook, together with status code `200`.
+
+3. To update the new webhook, call `PUT /apps/{app-id}/webhooks/{webhook-id}`, with a request body. For example:
+
+    *  API call:
+
+        ```http {linenos=false}
+        PUT /apps/80a28d6e-c5fc-43d9-87c2-d7d56b07542e/webhooks/msg_2M605iBQRge9hTgpYg7fKXQubaw
+        ```
+    *  Request body:
+
+        ```json
+        {
+          "name": "string",
+          "url": "https://some.domain.com/webhooks",
+          "eventTypes": [
+            "teamserver.push"
+          ],
+          "isActive": true,
+          "validationSecret": "PMJhiGo1nTL6wlNyZVFh5v9rLZdcLsG2O",
+          "headers": [
+            {
+              "key": "Authorization",
+              "value": "Beaerer DG4R4GT6R43"
+            }
+          ]
+        }
+        ```
+
+    If the update succeeds, you should receive status code `202`. You can get the updated webhook details by calling `GET apps/{app-id}/webhooks/{webhook-id}`.
+
+
+## 4 API Reference
+
+{{< swaggerui src="/openapi-spec/webhooks.yaml"  >}}

content/en/docs/apidocs-mxsdk/apidocs/webhooks-sprints.md

@@ -4,7 +4,7 @@ linktitle: "Webhooks for Stories/Sprints"
 url: /apidocs-mxsdk/apidocs/webhooks-sprints/
 category: "API Documentation"
 description: "These webhooks allow you to build or set up Mendix Platform connectors that subscribe to certain events on the Developer Portal."
-weight: 97
+weight: 100
 ---
 
 ## 1 Introduction

content/en/docs/releasenotes/developer-portal/_index.md

@@ -17,6 +17,12 @@ To see the current status of the Mendix Developer Portal and Control Center, see
 
 ## 2023
 
+### June 15th, 2023
+
+#### New Features
+
+* We have released [Webhooks API](/apidocs-mxsdk/apidocs/webhooks-api/) for Beta usage.
+
 ### June 1st, 2023
 
 #### Improvements