Skip to content

Commit

Permalink
GITBOOK-7: 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 Nov 1, 2023
1 parent edfb6ae commit 2599233
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 119 deletions.
96 changes: 3 additions & 93 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,99 +6,9 @@ It is possible to use its components as they are provided or use the base contra

### Sending and Receiving

The framework provides two major capabilities to the applications using its libraries
The framework provides three major capabilities to the applications using its libraries

<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>
<table><thead><tr><th width="209.5">Capability</th><th>Description</th></tr></thead><tbody><tr><td><a href="send_webhooks/"><strong>Send Webhooks</strong></a></td><td>Send a Webhook message to a receiver, enforcing formatting, integrity and retry rules</td></tr><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 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.
The two sending capabilities (_send_ and _notify_) are disconnected from the receiving capability, 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.

##





## Receiving Webhooks

The framework also provides a set of services that can be used to receive webhooks from external systems, and to process them.

To do so, you need to add the `Deveel.Webhooks.Receiver.AspNetCore` library to your project, that must be an _ASP.NET Core_ application.

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

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

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

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

### Configuring the Receiver

The receiver is configured using the `AddWebhooksReceiver` extension method on the `IServiceCollection` interface.

To run the receiver, you need to add the `UseWebhooksReceiver` middleware to the pipeline of your application, specifying the path where the receiver will be listening for the incoming webhooks.

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
using System;

using Microsoft.Extensions.Configuration;

using Deveel.Webhooks;

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

public IConfiguration Configuation { get; }

public void Configure(IServiceCollection services) {
services.AddWebhooksReceiver<MyWebhook>()
.AddHandler<MyWebhookHandler>();
}

public void Configure(IApplicationBuilder app) {
app.UseRouting();

app.UseWebhooksReceiver("/my-webhook");
}
}
}
```

The `AddWebhooksReceiver` method accepts a generic type parameter that specifies the type of the webhook that will be received by the receiver: this allows to accept and process multiple webhooks in the same application.

### Handling Webhooks

The receiver will invoke the registered handlers in the order they are registered, that allows to process the incoming webhook in a pipeline.

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

```csharp
using System;

using Deveel.Webhooks;

namespace Example {
public class MyWebhookHandler : IWebhookHandler<MyWebhook> {
private readonly ILogger<MyWebhookHandler> logger;

public MyWebhookHandler(ILogger<MyWebhookHandler> logger) {
this.logger = logger;
}

public Task HandleAsync(MyWebhook webhook, CancellationToken cancellationToken) {
logger.LogInformation("Received webhook {0}", webhook.Id);

// Do something with the webhook
}
}
}
```
65 changes: 44 additions & 21 deletions docs/notifications/webhook_subscription_filters.md
View file
Original file line number Diff line number Diff line change
@@ -1,41 +1,64 @@
# Filtering Webhook Subscriptions

To allow a webhook to be triggered only when a specific event occurs, subscriptions can define some filtering conditions that are evaluated before the webhook is delivered.
By design, webhook subscriptions are bound to a set of _event types_, and they are resolved on the occurrence of one or more of the events matching the type subscribed.

Such capability is useful to avoid sending unnecessary notifications to the webhook endpoint, and to reduce the load on the webhook endpoint, or for even implementing a routing mechanism to deliver the notifications to different endpoints.
It is possible to define _second-level filtering_ on the subscription, applying filters that will be evaluated, for the notification to be delivered to the subscriber.

## Filter Evaluators
Such capability is useful for scenarios like

The filtering conditions are evaluated by a set of services implementing the `IFilterEvaluator` interface, that is in fact a filtering engine.
* Avoid sending unnecessary notifications to the receiver
* &#x20;Reduce the load on the receiver
* Routing the delivery of the notifications to different receivers

When no filtering service is registered, the notification service will not evaluate any filtering condition, and will deliver the notification to the webhook endpoint, even if the subscription defines some filtering conditions.
## Webhook Filter Evaluators

To enable the filtering capability, the `IFilterEvaluator` service must be registered through the notification service builder:
Webhook subscriptions might include additional filters, such as IWebhookSubscriptionFilter, specifying the format in which they are expressed: a matching service supporting that format must be present in the application, for the evaluation to be performed.

```csharp
These filtering conditions are evaluated by services implementing the `IWebhookFilterEvaluator` interface, that is in fact a filtering engine.

By default, when no filtering service is registered in the application to support a specific format of the webhook subscription's filter, the notification service will fail, and will not deliver the notification to the receiver.

#### Registering the Filter Service

To enable the filtering capability, the `IWebFilterEvaluator` service must be registered through the notification service builder:

```csharp
namespace Example {
public class Startup {
public void ConfigureServices(IServiceCollection services) {
services.AddWebhookNotifier(webhooks => {
// Register the filter evaluator service that
// is using the "linq" syntax
webhooks.UseDynamicLinq();
});
}
}
public void ConfigureServices(IServiceCollection services) {
services.AddWebhookNotifier<MyWebhook>(webhooks => {
// Register the filter evaluator service that
// is using the "linq" syntax
webhooks.UseDynamicLinq();
});
}
}
}
```

The filtering engine is invoked with the instance of the webhook to be delivered, and the filtering expressions are evaluated against its structure and data: keep in mind this when creating the filtering conditions.
In the above code, we registered the `DynamicLinqFilterEvaluator`, which is a service provided in the [Deveel.Webhooks.DynamicLinq](https://www.nuget.org/packages/Deveel.Webhooks.DynamicLinq) package and that uses the [DynamicLINQ](https://dynamic-linq.net/) syntax to evaluate filters.

### Evaluating Webhooks

The filtering engine is invoked with the instance of the webhook object to be delivered, and the filtering expressions are evaluated against its structure and data: keep in mind this when creating the filtering conditions.

The representation of the webhook is dependent on the implementation of the serialization service (eg. `System.Text.Json`, `Newtonsoft.Json` or `System.Xml`) and the format of the webhook payload (either `json` or `xml`): these serializer might have different behaviors when serializing the webhook object (such as attributes or properties, or the casing of the names), and the filtering conditions must be defined accordingly.

## LINQ Filters

Currently the framework provides the service `DynamicLinqFilterEvaluator` that provides filtering capabilities using the LINQ syntax, that is a very powerful and flexible syntax to define filtering conditions.
As mentioned above, the framework provides the `DynamicLinqFilterEvaluator` service, which provides filtering capabilities using the LINQ syntax, a very powerful and flexible syntax to define filtering conditions.

For example, considering a webhook that is serialiazed as a JSON object as the following one:
You can install it by calling the following command on the root of your project:

```bash
dotnet add package Deveel.Webhooks.DynamicLinq --version 2.1.5
```

To enable it you will have to invoke the `.UseDynamicLinqFilters()`, like in the example above.

#### Example Filter

For example, consider a webhook that is serialized as a JSON object as the following one:

```json
{
Expand All @@ -49,10 +72,10 @@ For example, considering a webhook that is serialiazed as a JSON object as the f

The filtering expression

```linq
```csharp
event_type == "user.created" && user_name.startsWith("anto")
```

will evaluate to `true` if the webhook is delivered for the event `user.created` and the user name starts with `anto`.
will evaluate to `true` if the webhook is for the event `user.created` and the user name starts with `anto`.

**Note** - The engine does not provide any access to an external context than the webhook object itself, so it is not possible to access external data or services to evaluate the filtering conditions.
**Note** - The engine does not provide any access to an external context other than the webhook object itself: this means that is not possible to access external data or services to evaluate the filtering conditions.
96 changes: 91 additions & 5 deletions docs/receivers/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,95 @@
# Receivers

## Receiving Webhooks

The framework also provides a set of services that can be used to receive webhooks from external systems and to process them.

To do so, you need to add the `Deveel.Webhooks.Receiver.AspNetCore` library to your project, which must be an _ASP.NET Core_ application.

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

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

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

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

### Configuring the Receiver

The receiver is configured using the `AddWebhooksReceiver` extension method on the `IServiceCollection` interface.

To run the receiver, you need to add the `UseWebhooksReceiver` middleware to the pipeline of your application, specifying the path where the receiver will be listening for the incoming webhooks.

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
using System;

using Microsoft.Extensions.Configuration;

using Deveel.Webhooks;

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

public IConfiguration Configuation { get; }

public void Configure(IServiceCollection services) {
services.AddWebhooksReceiver<MyWebhook>()
.AddHandler<MyWebhookHandler>();
}

public void Configure(IApplicationBuilder app) {
app.UseRouting();
app.UseWebhooksReceiver("/my-webhook");
}
}
}
```

The `AddWebhooksReceiver` method accepts a generic type parameter that specifies the type of the webhook that will be received by the receiver: this allows to accept and process multiple webhooks in the same application.

### Handling Webhooks

The receiver will invoke the registered handlers in the order they are registered, that allows to process the incoming webhook in a pipeline.

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

```csharp
using System;

using Deveel.Webhooks;

namespace Example {
public class MyWebhookHandler : IWebhookHandler<MyWebhook> {
private readonly ILogger<MyWebhookHandler> logger;

public MyWebhookHandler(ILogger<MyWebhookHandler> logger) {
this.logger = logger;
}

public Task HandleAsync(MyWebhook webhook, CancellationToken cancellationToken) {
logger.LogInformation("Received webhook {0}", webhook.Id);

// Do something with the webhook
}
}
}
```



The framework provides a set of libraries that can be used to receive webhooks from external sources.

| Receiver | Description |
| ------------------------------------ | -------------------------------------------------- |
| **[Facebook](facebook_receiver.md)** | Receive webhooks from Facebook Messenger |
| **[SendGrid](sendgrid_receiver.md)** | Receive webhooks and emails from SendGrid |
| **[Twilio](twilio_receiver.md)** | Receive webhooks and SMS/WhatsApp messages from Twilio |
| Receiver | Description |
| ------------------------------------- | ------------------------------------------------------ |
| [**Facebook**](facebook\_receiver.md) | Receive webhooks from Facebook Messenger |
| [**SendGrid**](sendgrid\_receiver.md) | Receive webhooks and emails from SendGrid |
| [**Twilio**](twilio\_receiver.md) | Receive webhooks and SMS/WhatsApp messages from Twilio |

0 comments on commit 2599233

Please sign in to comment.