docs(webhook): improve structure of webhook section

Author: Sebastian Sauerer

docs/webhooks.md

@@ -15,7 +15,7 @@ Webhooks can be comfortably configured and managed by admin users in epilot port
 
 [Webhooks API Documentation](/api/webhooks)
 
-# Data Transmission
+## Data Transmission
 Webhooks do use the `Transfer-Encoding: chunked` mechanism when sending HTTP requests. This applies to webhook payloads triggered by various events in the system, ensuring that data is efficiently transmitted to your server.
 
 ### What is Transfer-Encoding: chunked?
@@ -34,20 +34,27 @@ To ensure proper handling of our webhook payloads, your server must:
 - Process Data in Chunks: If necessary, ensure your application processes the incoming data incrementally as it arrives.
 - End-of-Transfer Detection: Be aware that the payload transmission is complete when a final, empty chunk is received.
 
-### Limitation
+### Limitations
 The chunked transfer encoding mechanism is not supported by all servers. If your server does not support this feature, please contact our support team for assistance.
 
 Already known services which do not support chunked transfer encoding are:
 - [Microsoft Power Automate](https://www.microsoft.com/de-de/power-platform/products/power-automate?market=de)
 
-# Synchronous invocation
+## Webhook Payload Structure
+
+You can use the Entity API to get a full [JSON schema](/api/entity#tag/Schemas/operation/getJsonSchema) and a [JSON example](/api/entity#tag/Schemas/operation/getSchemaExample) of an entity part of your webhook. Alternatively, you can download these from the 360 Portal for each of your entities from the entity builder UI.
+
+![Export Entity Schema](../static/img/export-entity-schema.png)
+
+
+## Synchronous invocation
 To get immediate feedback on the success of a webhook request, the webhook can be configured to be invoked synchronously. This will cause the webhook to wait for the response of the request before proceeding. If the request fails, the webhook will be flagged as unsuccessful. This feature has to be enabled in the webhook action of the automation configuration.
 ![Option to enable sync webhooks](../static/img/automation-sync-webhook.png)
 
 ### Limitations
 Sync webhooks are limited to a maximum duration of 30 seconds. If the request exceeds this time limit, it will be automatically aborted, prompting the webhook to retry the request up to 2 times. If, after these retries, the request continues to fail, the webhook will be flagged as unsuccessful.
 
-# Customization
+## Customization
 
 ### Payload configuration
 
@@ -79,20 +86,13 @@ Customizing the payload of an incoming webhook request is entirely feasible. The
 
 ![Custom Webhook Payload Configuration](../static/img/webhook-custom-payload.png)
 
-### Entity schemas
-
-You can use the Entity API to get a full [JSON schema](http://localhost:3000/api/entity#tag/Schemas/operation/getJsonSchema) and a [JSON example](/api/entity#tag/Schemas/operation/getSchemaExample) of an entity part of your webhook. Alternatively, you can download these from the 360 Portal for each of your entities from the entity builder UI.
-
-![Export Entity Schema](../static/img/export-entity-schema.png)
-
 ### Custom oauth parameter
 
 Custom OAuth parameters can be seamlessly integrated into the webhook configuration process. These parameters can be included as part of the OAuth request, appended as body, query, or header parameters. This feature empowers users to augment the OAuth request with supplementary information as needed, enhancing the flexibility and customization options within the authentication flow.
 
 ![Custom Webhook Ouath Parameter](../static/img/webhook-custom-oauth.png)
 
+## Limitations
 
-# Limitations
-
-## Timeout
+### Timeout
 As previously mentioned, the webhook request times out after 30 seconds for synchronous webhooks. For asynchronous webhooks, the request will not time out, but the webhook will be flagged as unsuccessful if the request takes longer than 2 minutes to complete. This is to prevent the webhook from being stuck in a pending state indefinitely. Contact support if you need to increase this timeout. Keep in mind that for long running requests, it is recommend to handle them asynchronously on the 3rd party side and return a 202 Accepted response to the webhook request.