Skip to content

Commit

Permalink
GITBOOK-4: change request with no subject merged in GitBook
Browse files Browse the repository at this point in the history
  • Loading branch information
@tsutomi @gitbook-bot
tsutomi authored and gitbook-bot committed Oct 28, 2023
1 parent 4b4d059 commit 951c0c1
Show file tree
Hide file tree
Showing 15 changed files with 428 additions and 570 deletions.
26 changes: 13 additions & 13 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
# Deveel Webhooks Documentation
# Deveel Webhooks

Here you can find a documentation of the `Deveel Webhooks` framework, to help you getting started with the libraries and functions that compose it and to understand how it works.
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.

## Introduction

The framework is composed by a set of libraries that can be used, at different degrees, to implement a system that allows applications to send and receive webhooks.
The framework is composed of a set of libraries that can be used, at different degrees, to implement a system that allows applications to send and receive webhooks.

* **Sending Webhooks** - Using libraries of the framework you can send webhooks to receivers, based on your own logic and rules.
* **Receiving Webhooks** - The framework provides a set libraries implementing the capabilities for receiving webhooks from senders, reacting to events from external systems (such as Twilio, SendGrid, Facebook, etc.).
* **Notifications** - The framework provides a set of libraries that can be used to manage subscriptions to events, notify subscribing applications of events occurred in your system.
* **Receiving Webhooks** - The framework provides a set of libraries implementing the capabilities for receiving webhooks from senders and reacting to events from external systems (such as Twilio, SendGrid, Facebook, etc.).
* **Notifications** - The framework provides a set of libraries that can be used to manage subscriptions to events and notify subscribing applications of events that occurred in your system.

---
***

Read more about this framework:

| Topic | Description |
| ------ | ------------- |
| **[Concepts](concepts/README.md)** | A list of basic concepts used in the framework |
| **[Getting Started](getting_started.md)** | A quick guide to start using the framework |
| **[Sending Webhooks](send_webhooks.md)** | Sending webhooks messages to receivers |
| **[Receiving Webhooks](receivers/README.md)** | Receiving webhooks from senders |
| **[Notifications](notifications/README.md)** | Notify subscribing applications of events occurred in your system |
| Topic | Description |
| ----------------------------------------- | ----------------------------------------------------------------- |
| [**Concepts**](concepts/) | A list of basic concepts used in the framework |
| [**Getting Started**](getting-started.md) | A quick guide to start using the framework |
| [**Sending Webhooks**](send\_webhooks/) | Sending webhooks messages to receivers |
| [**Receiving Webhooks**](receivers/) | Receiving webhooks from senders |
| [**Notifications**](notifications/) | Notify subscribing applications of events occurred in your system |
14 changes: 8 additions & 6 deletions docs/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,17 @@
* [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)
* [Sending Webhooks](send\_webhooks/README.md)
* [Configuring the Sender](send\_webhooks/configuring-the-sender.md)
* [Signing Webhooks](send\_webhooks/signing-webhooks.md)
* [Webhook Serialization](send\_webhooks/webhook-serialization.md)
* [Webhook Notifications](notifications/README.md)
* [Webhook Subscriptions Management](notifications/webhook-subscriptions-management/README.md)
* [Data Layers](notifications/webhook-subscriptions-management/webhook\_subscription\_data\_layers/README.md)
* [Entity Framework Layer](notifications/webhook-subscriptions-management/webhook\_subscription\_data\_layers/webhook\_subscription\_ef.md)
* [The WebhookNotifier Service](notifications/webhook\_notifier.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)
Expand Down
230 changes: 12 additions & 218 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -1,228 +1,22 @@
# Getting Started

The overall design of this framework is open and extensible (implementing the traditional [Open-Closed Principle](https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle)), that means base contracts can be extended, composed or replaced.
The overall design of this framework is open and extensible (implementing the traditional [Open-Closed Principle](https://en.wikipedia.org/wiki/Open%E2%80%93closed\_principle)), which means base contracts can be extended, composed, or replaced.

It is possible to use its components as they are provided, or use the base contracts to extend single functions, while still using the rest of the provisioning.
It is possible to use its components as they are provided or use the base contracts to extend single functions, while still using the rest of the provisioning.

## Intall the Required Libraries
### Sending and Receiving

The overall set of libraries are available through [NuGet](https://nuget.org), and can be installed and restored easily once configured in your projects.
The framework provides two major capabilities to the applications using its libraries

At the moment (_November 2023_) they are developed as `.NET 6.0` and thus compatible with all the profiles of the .NET framework greater or equal than this.
<table><thead><tr><th width="209.5">Capability</th><th>Description</th></tr></thead><tbody><tr><td><a href="notifications/"><strong>Notify Webhooks</strong></a></td><td>Communicate the occurrence of an event in a system to an external application that is listening for those events </td></tr><tr><td><a href="receivers/"><strong>Receive Webhooks</strong></a></td><td>Accepts and processes a notification from an external system, to trigger any related process</td></tr></tbody></table>

The core library of the framework is `Deveel.Webhooks` and can be installed through the `dotnet` tool command line
The two capabilities are disconnected from one other since they represent two different parts of the communication channel (the _Sender_ and the _Receiver_): as such the architecture of the framework is designed so that they don't depend on each other's.

```sh
$ dotnet add package Deveel.Webhooks
```

Or by editing your `.csproj` file and adding a `<PackageReference>` entry.

``` xml
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<TargetFramework>ne6.0</TargetFramework>
...

</PropertyGroup>

<ItemGroup>
<PackageReference Include="Deveel.Webhooks" Version="2.1.1" />
...
</ItemGroup>
</Project>
```

This provides all the functions that are needed to manage subscriptions and send webhooks to a given destination, activating the notification process (although this one would require external instrumentations, for resolving subscriptions and other advanced functions).

## Adding the Webhook Service

To begin using the functions of the webhook service, all that you need is to invoke the `.AddWebhooks()` function of the service collection in the instrumentation of your application: this will add the required default services to the container, enabling the application to start notifying events to the registered recipients.

For example, 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 enable these functions like this:

```csharp

using System;

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

using Deveel.Webhooks;

namespace Example {
public class Startup {
public Startup(IConfiguration config) {
Configuration = config;
}

public IConfiguration Configuration { get; }

public void Configure(IServiceCollection services) {
// ... add any other service you need ...
// this call adds the basic services for sending of webhooks
// using the default configurations
services.AddWebhooks<MyWebhook>();
}
}
}

```

**Note**: To be able to notify events, you need to provide a type that implements the `IWebhookSubscriptionResolver` interface, that can be used to resolve the subscriptions for a given event. This is not provided by the core library by default, and you can add implementations that are specific for a given storage system (like the one provided by the `Deveel.Webhooks.MongoDb` library).

### Configuring the Delivery Behavior

The framework provides a default behavior for the delivery of webhooks to the registered recipients, but you can configure the behavior of the service to suit your needs.

The library `Deveel.Webhooks` depends from the `Deveel.Webhooks.Sender` library, which provides the needed functions to send webhooks to receivers: you will find the abstractions and helpers to configure the behavior of the webhook delivery to recipient systems, controlling aspects of the process like _payload formatting_, _retries on failures_, _signatures_.

You have several options to configure the service, and therefore you are free to chose the methodology that suits you best.

### The WebhookSenderOptions

The `WebhookSenderOptions` class provides a set of properties that can be used to configure the behavior of the webhook sender.

The configurations are evolving with the versions of the framework, and the following ones apply to the current version (`1.1.6`) of the library.

``` csharp

var options = new WebhookSenderOptions {
// When using the IHttpClientFactory, this is the name of the client
// that will be used to send the webhooks
HttpClientName = "my-http-client",

// A set of default headers that will be added to the requests
// sent to the webhook recipients
DefaultHeaders = new Dictionary<string, string> {
// The default headers that will be added to the requests
// sent to the webhook recipients
["X-Sender"] = "My-Webhook-Sender/1.0"
},

// The default format of the payload that will be sent to the
// webhook recipients (possible values are Json and Xml)
DefaultFormat = WebhookPayloadFormat.Json,

// The default timeout for the requests sent to the webhook
// recipients to be completed, before being considered failed
Timeout = TimeSpan.FromSeconds(30),

// The default retry options for the requests sent to the webhook
// recipients, that can be overridden by the specific subscription
// configurations
Retry = new WebhookRetryOptions {
// The default number of retries that will be performed
// after a failed request, before giving up
MaxRetries = 3,

// The default delay between retries
Delay = TimeSpan.FromSeconds(5),

// The default timeout for each retry request
// before being considered failed
Timeout = TimeSpan.FromSeconds(3)
},

// The default signature options for the requests sent to the webhook
// recipients, that can be overridden by the specific subscription
// configurations
Singature = new WebhookSenderSignatureOptions {
// The default location within the request where the signature
// will be added (possible values are Header and QueryString)
Location = WebhookSignatureLocation.Header,

// The default name of the header that carries the signature,
// when the location of the signature is the Header
HeaderName = "X-Signature",

// The default name of the query string parameter that carries
// the signature, when the location of the signature is the QueryString
QueryParameter = "signature",

// The default algorithm that will be used to sign the requests
// sent to the webhook recipients
Algorithm = WebhookSignatureAlgorithm.HmacSha256,

// The name of the query string parameter that will be used to
// specify the algorithm used for the signature
AlgorithmQueryParameter = "alg_sig"
}
};

```
##

Mind that every subscription can override some of the default options, and you can also provide a custom implementation of the `IWebhookSender` interface to customize the behavior of the delivery process.

### IConfiguration Pattern

If you keep your configurations in an `appsetting.json` file, environment variables, secrets, implementing a typical pattern of the _ASP.NET_ applications, you can invoke the overloads provided by `Deveel.Webhook` that access the available instances of `IConfiguration`.

``` csharp
using System;

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

using Deveel.Webhooks;

namespace Example {
public class Startup {
public Startup(IConfiguration configuration) {
Configuration = configuration;
}

public IConfiguration Configuation { get; }

public void Configure(IServiceCollection services) {
// The configurations are specified in the 'Webhooks:Sender'
// section of the configuration instance, and the service
// will find the IConfiguration instance within the
// container and use it to configure the service
services.AddWebhooks<MyWebhook>("Webhooks:Sender");
}
}
}
```

After this, an instance of `IOptions<WebhookDeliveryOptions>` is available for injection in the webhook services or in your code.

Given the design of the service, it will also be possible to access a webhook-specific instance of `IOptions<WebhookDeliveryOptions>` for a given webhook type, using the `IOptionsSnapshot<TOptions>` service, using the type name of the webhook as the key (eg. `IOptionsSnapshot<WebhookSenderOptions>.Get("MyWebhook")`).

### Manual Configuration

If you prefer to configure the service manually, you can use the `AddWebhooks` overload that accepts an instance of `WebhookSenderOptions` as parameter.

``` csharp
using System;

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

using Deveel.Webhooks;

namespace Example {
public class Startup {
public Startup(IConfiguration configuration) {
Configuration = configuration;
}

public IConfiguration Configuation { get; }

public void Configure(IServiceCollection services) {
services.AddHttpClient("my-http-client");

services.AddWebhooks<MyWebhook>(options => {
options.HttpClientName = "my-http-client";
});
}
}
}
```

Like in the previous case, an instance of `IOptionsSnapshot<WebhookSenderOptions>` is available for injection in the webhook services or in your code.

## Receiving Webhooks

Expand All @@ -232,13 +26,13 @@ To do so, you need to add the `Deveel.Webhooks.Receiver.AspNetCore` library to y

You can add the library to your project using the `dotnet` command line tool:

``` bash
```bash
dotnet add package Deveel.Webhooks.Receiver.AspNetCore
```

or add the following line to your `csproj` file:

``` xml
```xml
<PackageReference Include="Deveel.Webhooks.Receiver.AspNetCore" Version="1.1.6" />
```

Expand All @@ -250,7 +44,7 @@ To run the receiver, you need to add the `UseWebhooksReceiver` middleware to the

When the service is configured with a webhook receiver, this will be invoked when a webhook is received, allowing the processing of the incoming webhook.

``` csharp
```csharp
using System;

using Microsoft.Extensions.Configuration;
Expand Down Expand Up @@ -287,7 +81,7 @@ The receiver will invoke the registered handlers in the order they are registere

Handlers can use dependency injection to access the services registered in the application.

``` csharp
```csharp
using System;

using Deveel.Webhooks;
Expand All @@ -307,4 +101,4 @@ namespace Example {
}
}
}
```
```
Loading

0 comments on commit 951c0c1

Please sign in to comment.