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

docs/FAQS.md

@@ -1,28 +1,12 @@
-<!--
- 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.
--->
-
-# Deveel Webhooks Frequently Asked Questions
+# Frequently Asked Questions
 
 ## Q: Why have you developed another Webhook management library
 
 A: We didn't have the ambition to develop this project, but rather to use some already available, anyway given the conditions we were in, we could not find any fitting alternative:
 
-* **[Microsoft's ASP.NET Webhook Framework](https://github.com/aspnet/WebHooks)**, before being retired, supported only the .NET 4.6 framework
-* **[Microsot's ASP.NET Core Webhook Framework](https://github.com/aspnet/AspLabs/tree/main/src/WebHooks)** was _demoted_ to an experimental project (within the scope of [AspNetLabs](https://github.com/aspnet/AspLabs) space), and anyway did not provide any capability for the management of subscriptions, or logging results of deliveries
-* **[ASP.NET Boilerplate (by Volosoft)](https://github.com/aspnetboilerplate/aspnetboilerplate)** provides functionalities for the management and sending of webhooks that are embedded into a more extended framework, that we didn't want to use in its entirety.
+* [**Microsoft's ASP.NET Webhook Framework**](https://github.com/aspnet/WebHooks), before being retired, supported only the .NET 4.6 framework
+* [**Microsot's ASP.NET Core Webhook Framework**](https://github.com/aspnet/AspLabs/tree/main/src/WebHooks) was _demoted_ to an experimental project (within the scope of [AspNetLabs](https://github.com/aspnet/AspLabs) space), and anyway did not provide any capability for the management of subscriptions, or logging results of deliveries
+* [**ASP.NET Boilerplate (by Volosoft)**](https://github.com/aspnetboilerplate/aspnetboilerplate) provides functionalities for the management and sending of webhooks that are embedded into a more extended framework, that we didn't want to use in its entirety.
 
 ## Q: Which .NET versions are supported by Deveel Webhooks?
 
@@ -42,7 +26,7 @@ A: As pointed out in the answer provided above (on the motivations of this proje
 
 A: Not at the moment, but any contribution is welcome... :)
 
-The data model of subscriptions and webhooks is not complex and should not be a challenge to contribute with alternatives (please refer to the [contributing guidelines](/CONTRIBUTING.md)).
+The data model of subscriptions and webhooks is not complex and should not be a challenge to contribute with alternatives (please refer to the [contributing guidelines](../CONTRIBUTING.md)).
 
 ## Q: Does Deveel Webhooks support webhook subscriptions?
 
@@ -88,10 +72,10 @@ A: No. It is a good idea to explore for future implementations.
 
 A: At the moment the framework supports the following external webhook providers:
 
-* **[Facebook](facebook_receiver.md)**
-* **[SendGrid](sendgrid_receiver.md)**
-* **[Twilio](twilio_receiver.md)**
+* [**Facebook**](receivers/facebook\_receiver.md)
+* [**SendGrid**](receivers/sendgrid\_receiver.md)
+* [**Twilio**](receivers/twilio\_receiver.md)
 
 Follow the issues of this project to see which providers are planned to be supported in the future.
 
-The framework also provides a generic receiver that can be used to implement a webhook receiver for any other provider, including your own applications.
+The framework also provides a generic receiver that can be used to implement a webhook receiver for any other provider, including your own applications.

docs/SUMMARY.md

@@ -0,0 +1,24 @@
+# Table of contents
+
+* [Deveel Webhooks](README.md)
+* [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)
+* [Sending Webhooks](send\_webhooks.md)
+* [Webhook Notifications](notifications/README.md)
+  * [Producing Custom Data Factories](notifications/custom\_datafactory.md)
+  * [WebhookNotifier](notifications/webhook\_notifier.md)
+  * [Webhook Subscription Management Data Layers](notifications/webhook\_subscription\_data\_layers.md)
+  * [advanced\_usage\_ef](notifications/webhook\_subscription\_ef.md)
+  * [Filtering Webhook Subscriptions](notifications/webhook\_subscription\_filters.md)
+  * [basic\_usage\_management](notifications/webhook\_subscription\_management.md)
+  * [Webhook Management Data Layers](notifications/webhook\_subscription\_mongodb.md)
+* [Receivers](receivers/README.md)
+  * [Webhook Receivers](receivers/custom\_receiver.md)
+  * [Facebook Webhook Receiver](receivers/facebook\_receiver.md)
+  * [Receiving Webhooks](receivers/receive\_webhooks.md)
+  * [SendGrid Webhook and E-Mail Receiver](receivers/sendgrid\_receiver.md)
+  * [Twilio Webhook Receiver](receivers/twilio\_receiver.md)
+* [Developer Guidelines](developer\_guide.md)
+* [Frequently Asked Questions](FAQS.md)

docs/send_webhooks.md

@@ -1,30 +1,45 @@
-<!--
- 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.
--->
-
 # Sending Webhooks
 
-The simple act of sending Webhooks to receivers is not depdenent from the existence of subscriptions, and can be executed throug direct invocations to instances of the `IWebhookSender` service.
+The simple act of sending Webhooks to receivers is not dependent on the existence of subscriptions and can be executed through direct invocations to instances of the `IWebhookSender` service.
+
+### Requirements
+
+To use the sender functions in your applications, without any other additional feature (eg. _subscription management_, _notifications_, etc.) you must install the foundation library `Deveel.Webhooks.Sender`.
+
+You can do this by using the .NET command line on the root folder of your project
+
+```bash
+dotnet add package Deveel.Webhooks.Sender
+```
+
+Alternatively, you can add a reference in your project file
+
+```xml
+<PackageReference Include="Deveel.Webhooks.Sender" Version="2.1.1" />>
+```
+
+### Registering the Webook Sender
+
+The most common way to use the Webhook Sender is to register it in the collection of services of your application, using the _dependency injection_ pattern.
+
+You can use one of the overloads of the extension method `.AddWebhookSender<TWebhook>()` to the `IServiceCollection` contract.
+
+For example:
+
+```csharp
+services.AddWebhookSender<MyWebhook>()
+    .Configure(options => {
+        // ...
+    });
+```
 
-## Configuring the Webook Sender
+The method will register a default implementation of the `IWebhookSender<TWebhook>`, returning a builder to further configure the behavior of the sender (even replacing the default implementation with a custom sender).
 
-Although a Webhook Sender can be instantiated, configured used directly, the framework provides a set of extension methods that can be used to configure the service in a more convenient way, especially in contexts that require the use of Dependency Injection.
+#### Example Registration
 
-Assuming you are working on a traditional _[ASP.NET application model](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/?view=aspnetcore-6.0&tabs=windows)_, you can start using the sender functions of this framework through the _Dependency Injection_ (DI) pattern, including a default implementation of the sender during the Startup of your application, by calling the `.AddWebhooks()` extension method provided by _Deveel Webhooks_, and optionally configuring the behavior of the delivery:
+Assuming you are working on a traditional [_ASP.NET application model_](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/?view=aspnetcore-6.0\&tabs=windows), you can start using the sender functions of this framework through the _Dependency Injection_ (DI) pattern, including a default implementation of the sender during the Startup of your application, by calling the `.AddWebhooks()` extension method provided by _Deveel Webhooks_, and optionally configuring the behavior of the delivery:
 
-``` csharp
+```csharp
 using System;
 
 using Microsoft.Extensions.Configuration;
@@ -59,11 +74,11 @@ namespace Example {
 
 ### Webhook Signatures
 
-A recommended practice for Webhooks is to sign the payloads of the messages, so that the receiver can verify the authenticity of the message. The framework provides a mechanism to sign the payloads of the messages, and to verify the signatures of the incoming messages.
+A recommended practice for Webhooks is to sign the payloads of the messages so that the receiver can verify the authenticity of the message. The framework provides a mechanism to sign the payloads of the messages and to verify the signatures of the incoming messages.
 
 The framework provides by default an implementation of a signature provider (the `IWebhookSigner` contract), that computes signatures using the 'HMAC-SHA-256' algorithm, but it is possible to add custom ones through the call to `.AddSigner<TSigner>()` of the service builder.
 
-``` csharp
+```csharp
 using System;
 
 using Microsoft.Extensions.Configuration;
@@ -95,7 +110,7 @@ The most common format for the payloads of Webhooks is the JSON format, but it i
 
 When initializing the sender, a default serializer for each format is added to the service, but it is possible to add custom ones through the call to `.UseJsonSerializer<TSerializer>()` or `.UseXmlSerializer<TSerializer>()` of the service builder.
 
-``` csharp
+```csharp
 
 using System;
 
@@ -125,11 +140,11 @@ namespace Example {
 
 ## Using the Webhook Sender
 
-At this point you can obtain from the service provider an instance of the `IWebhookSender<MyWebhook>` that is configured and ready to be used.
+At this point, you can obtain from the service provider an instance of the `IWebhookSender<MyWebhook>` that is configured and ready to be used.
 
 Assuming your application is using the _ASP.NET Core_ framework, you can inject the service in your controllers, and use it to send Webhooks to the receivers:
 
-``` csharp
+```csharp
 using System;
 
 using Deveel.Webhooks;
@@ -173,11 +188,11 @@ namespace Example {
 
 ### Webhook Destinations
 
-While the webhook represents a message that is sent to a receiver, the destination is the address of the receiver, complimented with additional configurations that can override the defaults set during the building of the sender service. 
+While the webhook represents a message that is sent to a receiver, the destination is the address of the receiver, complimented with additional configurations that can override the defaults set during the building of the sender service.
 
 In the context of _simple sending_ of Webhooks, the destination is represented by an instance of the `WebhookDestination` class.
 
-``` csharp
+```csharp
 
 var destination = new WebhookDestination("https://my-webhook-receiver.com/events/webhooks")
     .WithRetry(options => {
@@ -195,4 +210,4 @@ The result of the sending of a Webhook is represented by an instance of the `Web
 
 During the process of sending webhooks, the sender can perform multiple attempts to deliver the message to the receiver (depending on the retry configuration), and the result of the delivery is represented by an instance of the `WebhookDeliveryAttempt` class: a result can be considered successful if at least one attempt was successful, and it can be considered failed if all the attempts failed.
 
-You can use the `WebhookDeliveryResult` class to check the status of the delivery, and to retrieve the results of the attempts.
+You can use the `WebhookDeliveryResult` class to check the status of the delivery, and to retrieve the results of the attempts.