Skip to content

Commit 9df2495

Browse files
tsutomitsutomi
committed
Documentation and license headers
1 parent e65f72f commit 9df2495

File tree

78 files changed

+1435
-64
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

78 files changed

+1435
-64
lines changed

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,14 @@ The libraries currently provided by the framework are the following:
3232
| **Deveel.Webhooks.DynamicLinq** | The webhook subscription filtering engine that uses the [Dynamic LINQ](https://dynamic-linq.net/) expressions | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.DynamicLinq?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.DynamicLinq) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.DynamicLinq) |
3333
| **Deveel.Webhooks.Receiver.AspNetCore** | An implementation of the webhook receiver that is backed by [ASP.NET Core](https://dotnet.microsoft.com/apps/aspnet) | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.Receiver.AspNetCore?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.Receiver.AspNetCore) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.Receiver.AspNetCore) |
3434

35+
The following libraries extend the framework with receivers for specific providers:
36+
37+
| Library | Description | NuGet | GitHub (prerelease) |
38+
| ----------------------------------------| ---------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------- |---------------------|
39+
| **Deveel.Webhooks.Receiver.Twilio** | An implementation of the webhook receiver that is backed by [Twilio](https://twilio.com) SMS and WhatsApp messages | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.Receiver.Twilio?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.Receiver.Twilio) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.Receiver.Twilio) |
40+
| **Deveel.Webhooks.Receiver.SendGrid** | An implementation of the webhook and email receiver that is backed by [SendGrid](https://sendgrid.com) email messages | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.Receiver.SendGrid?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.Receiver.SendGrid) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.Receiver.SendGrid) |
41+
| **Deveel.Webhooks.Receiver.Facebook** | An implementation of the webhook receiver that is backed by [Facebook](https://facebook.com) Messenger messages | [![Nuget](https://img.shields.io/nuget/v/Deveel.Webhooks.Receiver.Facebook?label=NuGet&logo=nuget)](https://www.nuget.org/packages/Deveel.Webhooks.Receiver.Facebook) | [![GitHub](https://img.shields.io/static/v1?label=GitHub&message=preview&color=yellow&logo=github)](https://github.com/deveel/deveel.webhooks/pkgs/nuget/Deveel.Webhooks.Receiver.Facebook) |
42+
3543
You can obtain the stable versions of these libraries from the [NuGet Official](https://nuget.org) channel.
3644

3745
To get the latest pre-release versions of the packages you can restore from the [Deveel Package Manager](https://github.com/orgs/deveel/packages).

‎docs/README.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ Here you can find a documentation of the `Deveel Webhooks` framework, to help yo
2121

2222
## Basic Concepts
2323

24+
To set the domain model of the framework, we need to introduce some basic concepts that are used in the framework.
25+
2426
| Topic | Description |
2527
| ---------------------------------------------------- | ------------------------------------------ |
2628
| **[Webhook](concept_webhook.md)** | What is it a 'Webhook' and why I need it? |
@@ -29,21 +31,35 @@ Here you can find a documentation of the `Deveel Webhooks` framework, to help yo
2931
| **[Receivers](concept_webhook_receiver.md)** | What is a receiver of webooks? |
3032
| **[Notifications](concept_webhook_notification.md)** | What is a notification of events? |
3133

32-
## Tutorials
34+
## Basic Usage
35+
36+
The following tutorials will guide you through the basic usage of the framework, showing how to use the different components to send, receive and manage webhooks.
3337

3438
| Topic | Description |
3539
| ---------------------------------------------------------------------- | --------------------------------------------------------------------- |
3640
| **[Getting Started](getting_started.md)** | Getting started with `Deveel Webhooks` |
37-
| **[Basic Usage - Sending Webhooks](basic_usage_send.md)** | Manually sending webhooks (no subscriptions) |
38-
| **[Basic Usage - Subscription Management](basic_usage_management.md)** | Manage subscriptions to events (no sending) |
39-
| **[Basic Usage - Notify Webhooks](basic_usage_notify.md)** | Notify webhooks subscribers (management, transformations and sending) |
40-
| **[Basic Usage - Receiving Webhooks](basic_usage_receive.md)** | Receive webhooks from external sources |
41+
| **[Sending Webhooks](basic_usage_send.md)** | Manually sending webhooks (no subscriptions) |
42+
| **[Subscription Management](basic_usage_management.md)** | Manage subscriptions to events (no sending) |
43+
| **[Notify Webhooks](basic_usage_notify.md)** | Notify webhooks subscribers (management, transformations and sending) |
44+
| **[Receiving Webhooks](basic_usage_receive.md)** | Receive webhooks from external sources |
45+
46+
## Advanced Usage
4147

42-
## Extending
48+
A more advanced usage of the framework is possible by implementing custom components that can be used to extend the framework functionalities.
4349

4450
| Topic | Description |
4551
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
46-
| **[Advanced Usage - Filtering Subscriptions](advanced_usage_filters.md)** | Allow subscribers to filter webhooks on dynamic parameters |
47-
| **[Advanced Usage - Custom Data Factories](advanced_usage_custom_datafactory.md)** | Implement a component that transforms event data |
48-
| **[Advanced Usage - Custom Receivers](advanced_usage_custom_receiver.md)** | Implement parsers for receiving webhooks |
49-
| **[Advanced Usage - Using Data Layers](advanced_usage_data_layer.md)** | Use different data layers for the persistence of the webhook information model |
52+
| **[Filtering Subscriptions](advanced_usage_filters.md)** | Allow subscribers to filter webhooks on dynamic parameters |
53+
| **[Custom Data Factories](advanced_usage_custom_datafactory.md)** | Implement a component that transforms event data |
54+
| **[Custom Receivers](advanced_usage_custom_receiver.md)** | Implement parsers for receiving webhooks |
55+
| **[Using Data Layers](advanced_usage_data_layer.md)** | Use different data layers for the persistence of the webhook information model |
56+
57+
## Receivers
58+
59+
The framework provides a set of libraries that can be used to receive webhooks from external sources.
60+
61+
| Receiver | Description |
62+
| -------- | ----------- |
63+
| **[Facebook](facebook_receiver.md)** | Receive webhooks from Facebook Messenger |
64+
| **[SendGrid](sendgrid_receiver.md)** | Receive webhooks and emails from SendGrid |
65+
| **[Twilio](twilio_receiver.md)** | Receive webhooks and SMS/WhatsApp messages from Twilio |

‎docs/sendgrid_receiver.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# SendGrid Webhook and E-Mail Receiver
2+
3+
The framework provides a set of configurations and extensions to support the capabilities for receiving and processing SendGrid webhooks and e-mails.
4+
5+
## Installation
6+
7+
You can install the package from NuGet, running the following command in the console:
8+
9+
```bash
10+
dotnet add package Deveel.Webhooks.Receiver.SendGrid
11+
```
12+
13+
## Configuration
14+
15+
### Receiving Webhooks
16+
17+
To activate the SendGrid receiver you don't need many cerimonies or configurations, just add the following line to the `ConfigureServices` method of your `Startup` class (assuming you are using a classic ASP.NET Core application):
18+
19+
```csharp
20+
public void ConfigureServices(IServiceCollection services) {
21+
// ...
22+
services.AddSendGridReceiver()
23+
.AddHandler<SendGridWebhookHandler>();
24+
// ...
25+
}
26+
```
27+
28+
The above line will register the required services and configurations to the DI container, using the default configurations, so that the receiver can be used in the application.
29+
30+
If you need to customize directly the configurations, you can use the following overload of the `AddSendGridReceiver` method:
31+
32+
```csharp
33+
public void ConfigureServices(IServiceCollection services) {
34+
// ...
35+
services.AddSendGridReceiver(options => {
36+
options.VerifySignatures = true;
37+
options.Secret = "my-secret";
38+
});
39+
// ...
40+
}
41+
```
42+
43+
If your configurations reside in a configuration section of the `appsettings.json` file, you can use the following overload:
44+
45+
```csharp
46+
public void ConfigureServices(IServiceCollection services) {
47+
// ...
48+
services.AddSendGridReceiver("Webhooks:SendGrid")
49+
.AddHandler<SendGridWebhookHandler>();
50+
// ...
51+
}
52+
```
53+
54+
_Note: the above overload will use the `Webhooks:SendGrid` section of the configuration file to load the configurations, but any can be used_
55+
56+
### Receiving E-Mails
57+
58+
SendGrid and other providers of e-mail services support the capability to forward e-mails to a specific endpoint, so that the application can process them, using alternative methods than the classic SMTP protocol.
59+
60+
By nature, these HTTP requests are not considered as webhooks, but they are still HTTP requests that can be processed by the framework: in fact the receiver library provides a specific handler that can be used to process e-mails.
61+
62+
Since thes e-mails are not following the practices of webhooks, the receiver will not validate the signature of the request, but it will process it as it is, requiring no additional configurations.
63+
64+
To activate the e-mail receiver, you can use the following overload of the `AddSendGridEmailReceiver` method:
65+
66+
```csharp
67+
public void ConfigureServices(IServiceCollection services) {
68+
// ...
69+
services.AddSendGridEmailReceiver("/email/sendgrid")
70+
.AddHandler<SendGridEmailHandler>();
71+
// ...
72+
}
73+
```
74+
75+
76+
## Mapping Webhook Events
77+
78+
To map the events received from SendGrid to the handlers provided by the framework, you can use the `MapSendGridWebhook` and `MapSendGridEmail` extension methods of the `IApplicationBuilder` contract:
79+
80+
```csharp
81+
public void Configure(IApplicationBuilder app, IHostingEnvironment env) {
82+
// ...
83+
app.MapSendGridWebhook("/webhook/sendgrid");
84+
app.MapSendGridEmail("/email/sendgrid");
85+
86+
app.MapSendGridWebhook("/webhook/sendgrid/handled", webhook => {});
87+
88+
app.MapSendGridEmail("/email/sendgrid/handled", email => {});
89+
// ...
90+
}
91+
```
92+
93+
The framework will bind the incoming webhooks and emails to instances of the `SendGridWebhook` and `SendGridEmail` classes, that can be used to process the data received from the provider.

‎docs/twilio_receiver.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ Then, you need to configure the receiver in the `Configure` method of the `Start
3030
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
3131
// ...
3232
app.MapTwilioWebhook("/twilio/webhook");
33+
34+
app.MapTwilioWebhook("/twilio/other", webhook => {
35+
// ...
36+
});
3337
// ...
3438
}
3539
```

‎src/Deveel.Webhooks.Receiver.SendGrid.XUnit/Deveel.Webhooks.Receiver.SendGrid.XUnit.csproj‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,4 +32,7 @@
3232
<ProjectReference Include="..\Deveel.Webhooks.Receiver.SendGrid\Deveel.Webhooks.Receiver.SendGrid.csproj" />
3333
</ItemGroup>
3434

35+
<ItemGroup>
36+
<None Include="..\..\apl-2.licenseheader" Link="apl-2.licenseheader" />
37+
</ItemGroup>
3538
</Project>

‎src/Deveel.Webhooks.Receiver.SendGrid.XUnit/Usings.cs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,15 @@
1+
// Copyright 2022-2023 Deveel
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
115
global using Xunit;

‎src/Deveel.Webhooks.Receiver.SendGrid.XUnit/Webhooks/SendGridEmailTests.cs‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
1-
using System.Reflection.Metadata;
1+
// Copyright 2022-2023 Deveel
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
using System.Reflection.Metadata;
216
using System.Text;
317

418
using Deveel.Webhooks.SendGrid;

‎src/Deveel.Webhooks.Receiver.SendGrid.XUnit/Webhooks/SendGridWebhookTests.cs‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
1-
using Deveel.Webhooks.SendGrid;
1+
// Copyright 2022-2023 Deveel
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
using Deveel.Webhooks.SendGrid;
216

317
using Microsoft.AspNetCore.Http;
418
using Microsoft.Extensions.DependencyInjection;

‎src/Deveel.Webhooks.Receiver.SendGrid/Webhooks/Json/Base64StringConverter.cs‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
1-
using System;
1+
// Copyright 2022-2023 Deveel
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
using System;
216
using System.Collections.Generic;
317
using System.Linq;
418
using System.Text;

‎src/Deveel.Webhooks.Receiver.SendGrid/Webhooks/WebhookReceiverBuilderExtensions.cs‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,18 @@
1-
using System.Diagnostics.CodeAnalysis;
1+
// Copyright 2022-2023 Deveel
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
using System.Diagnostics.CodeAnalysis;
216

317
using Deveel.Webhooks.SendGrid;
418

0 commit comments

Comments
 (0)