GITBOOK-5: change request with no subject merged in GitBook

docs/README.md

@@ -1,3 +1,21 @@
+---
+coverY: 0
+layout:
+  cover:
+    visible: true
+    size: full
+  title:
+    visible: true
+  description:
+    visible: true
+  tableOfContents:
+    visible: false
+  outline:
+    visible: false
+  pagination:
+    visible: true
+---
+
 # Deveel Webhooks
 
 Here you can find documentation of the `Deveel Webhooks` framework, to help you get started with the libraries and functions that compose it and to understand how it works.

docs/SUMMARY.md

@@ -4,7 +4,10 @@
 * [Getting Started](getting-started.md)
 * [Concepts](concepts/README.md)
   * [What is a Webhook?](concepts/webhook.md)
-  * [What is a Webhook Subscription?](concepts/webook\_subscription.md)
+  * [What is a Webhook Subscription?](concepts/webook-subscription.md)
+  * [What is a Sender of Webhooks?](concepts/webhook-sender.md)
+  * [What is a Receiver of Webhooks?](concepts/webhooks-receivers.md)
+  * [What is an Event Notification?](concepts/webhook-notification.md)
 * [Sending Webhooks](send\_webhooks/README.md)
   * [Configuring the Sender](send\_webhooks/configuring-the-sender.md)
   * [Signing Webhooks](send\_webhooks/signing-webhooks.md)

docs/concepts/README.md

@@ -2,10 +2,10 @@
 
 The following concepts are used in this project:
 
-|  Topic  |  Description  |
-| ------- | ------------- |
-| **[Webhook](webhook.md)**  | What is it a 'Webhook' and why I need it?  |
-| **[Subscriptions](webhook_subscription.md)** | How does a subscription to an event works? |
-| **[Senders](webhook_sender.md)** | What is a sender of webooks? |
-| **[Receivers](webhook_receiver.md)** | What is a receiver of webooks? |
-| **[Notifications](webhook_notification.md)** | What is a notification of events?  |
+| Topic                                         | Description                                |
+| --------------------------------------------- | ------------------------------------------ |
+| [**Webhook**](webhook.md)                     | What is it a 'Webhook' and why I need it?  |
+| [**Subscriptions**](webhook\_subscription.md) | How does a subscription to an event works? |
+| [**Senders**](webhook-sender.md)              | What is a sender of webooks?               |
+| [**Receivers**](webhook-sender.md)            | What is a receiver of webooks?             |
+| **Notifications**                             | What is a notification of events?          |

docs/concepts/webhook-notification.md

@@ -0,0 +1,2 @@
+# What is an Event Notification?
+

docs/concepts/webhook-sender.md

@@ -0,0 +1,38 @@
+---
+layout:
+  title:
+    visible: true
+  description:
+    visible: false
+  tableOfContents:
+    visible: false
+  outline:
+    visible: true
+  pagination:
+    visible: true
+---
+
+# What is a Sender of Webhooks?
+
+Considering the overall network of communications, where Webhooks are messages exchanged between two applications, a Webhook Sender is an application that sends these messages to another application (or to a multitude of applications).
+
+In real life, you might consider the _Sender_ as the postman delivering a letter or a package to the destination, ensuring the address is correct and exists, that the postbox can hold the shipment, eventually coming back more than once at the address (if the recipient is not at home), accepting the signature, etc.
+
+As much as a postman wouldn't care if the letter or package was in delivery because of an agreement between the recipient and an organization, the same way a Webhook Sender doesn't have to necessarily require the knowledge that an application is expecting the message it is sending (this would be a [Webhook Subscription](webook-subscription.md)).
+
+### The Delivery Destination
+
+A Sender requires the specification of a Destination, to be able to attempt the delivery of Webhooks, which is like a postal address, following the example above.
+
+In most cases, this is simply a URL (_Universal Resource Locator_), that can be reached by an HTTP request, but in some scenarios, this can be enriched with further information instructing the sender on the behavior to have with it, when attempting to deliver a package (for example, we inform the sender to leave the package to our neighbor, if we are not at home, or to try reaching us only on Thursdays, etc.).
+
+Such destination-specific instructions would act as an exception to the regular behavior of the sender, which is described below.
+
+### The Sender Behavior
+
+When sending a Webhook to another party, the application sending messages should ensure that the destination is reachable, the message is well-formatted, its delivery is retried (in case of failures), and the integrity of the content is assured.
+
+This is done by a configured behavior, that typically provides the following elements of configuration
+
+<table><thead><tr><th width="209.5">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>Content Type</strong></td><td>The specification of the format of the contents of the Webhook message (eg. <em>JSON</em>, <em>XML</em>, <em>Form-Encoded</em>)</td></tr><tr><td><strong>Retry Strategy</strong></td><td>The methodology to deliver the message (eg. <em>Circuit Breaker,</em> <em>Exponential Backoff</em>, <em>Timeout</em>, etc.), and the configurations of retries (eg. <em>a maximum number of retries</em>, <em>delays between attempts</em>, etc.)</td></tr><tr><td><strong>Signature Method</strong></td><td>A methodology used to sign the Webhook payloads, so that the the receiver can ensure their integrity</td></tr><tr><td><strong>Context</strong></td><td>The set of contextual information informing the receiver of the origination of the Webhook (eg. <em>the machine name</em>, <em>the application type</em>, etc.)</td></tr></tbody></table>
+

docs/concepts/webhooks-receivers.md

@@ -0,0 +1,10 @@
+# What is a Receiver of Webhooks?
+
+As we have cleared out before, Webhooks are messages that inform an application of the occurrence of an event in a system: as such we consider the context of communications, where there are two (or more) parties sending and receiving messages between each other.
+
+In a specular way to the definition of the Webhook Sender, of which we made an analogy with a postman delivering a letter or a package, the Webhook Receiver can be considered the recipient (a person or a company), that physically receives the deliverable.
+
+Considering the real-life scenario of delivery of letters or packages, we all can be receivers, if we provide a postbox with our name on it, that we make available for postmen to access. 
+
+In some special cases of secure shipments, we might also be requested to sign a receipt to ensure that the packages or envelopes were actually delivered.
+

docs/concepts/webook_subscription.md → docs/concepts/webook-subscription.md

@@ -1,29 +1,14 @@
-<!--
- Copyright 2022 Deveel
- 
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
- 
-     http://www.apache.org/licenses/LICENSE-2.0
- 
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
 # What is a Webhook Subscription?
 
 It is easy to define the concept of subscription to the notification of a certain type of events, and we have several examples of this in our daily life:
-* We can subscribe to a newspaper to receive it every day, 
+
+* We can subscribe to a newspaper to receive it every day,
 * We can be opt-in to be notified when a new product is available in a shop by a phone call or an email
 * We can subscribe to a newsletter to be notified when a new article is published on a blog
 
 In all these cases, we are interested in being notified when something happens, and we are not interested in the details of the event itself: some of the elements of the event are relevant to us, and some of these elements are relevant for the publisher to know how and when to reach us.
 
-For the other party that has to notify us on the type of events we are interested in, it is important to know how to reach us, and it is important to know what we are interested in. 
+For the other party that has to notify us on the type of events we are interested in, it is important to know how to reach us, and it is important to know what we are interested in.
 
 In the case of a newspaper, the publisher needs to know our address, and the type of newspaper we want to receive. In the case of a shop, the publisher needs to know our phone number or email address, and the type of products we are interested in. In the case of a blog, the publisher needs to know our email address, and the type of articles we are interested in.
 
@@ -39,11 +24,15 @@ Subscriptions to events are typically indicating used by publisher to control th
 
 Although no formal specification for this type of objects was agreed and standardized, a typical pattern across the providers of services is to define the following elements:
 
-* **Subscription ID**: a unique identifier of the subscription, used to identify the subscription in the system
-* **Subscription Name**: a human-readable name of the subscription, used to identify the subscription in the system
-* **Event Type**: the type of event the subscription is interested in
-* **Event Criteria**: a set of criteria that the event must satisfy in order to be notified to the subscriber
-* **Endpoint**: the endpoint where the subscriber will be notified of the event
-* **Status**: the status of the subscription, which can be `ACTIVE`, `INACTIVE`, `EXPIRED`, `DELETED`
-* **Headers**: a set of headers that will be sent to the subscriber when the event occurs (usefull to identify a context)
-* **Secret Key**: a secret key that will be used to sign the notification to the subscriber
+
+
+| Attribute                | Description                                                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| **Subscription ID**      | A unique identifier of the subscription, used to identify the subscription in the system                   |
+| **Subscription Name**    | A human-readable name of the subscription, used to identify the subscription in the system                 |
+| **Event Type**           | The type of event the subscription is interested in                                                        |
+| **Event Criteria**       | A set of criteria that the event must satisfy in order to be notified to the subscriber                    |
+| **Destination Endpoint** | The endpoint where the subscriber will be notified of the event                                            |
+| **Status**               | The status of the subscription, which can be `ACTIVE`, `INACTIVE`, `EXPIRED`, `DELETED`                    |
+| **Headers**              | A set of headers that will be sent to the subscriber when the event occurs (usefull to identify a context) |
+| **Secret Key**           | A secret key that will be used to sign the notification to the subscriber                                  |