From 64bc57b1920ca4af36c5059c683a5054582aeb99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Keresztury?= Date: Thu, 18 Jun 2020 12:49:29 +0200 Subject: [PATCH 1/4] Change documentation and package metadata --- .../Mailgun.Models.SignedEvent.csproj | 9 +++++++++ README.md | 12 ++++++------ 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj b/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj index 3ae2d8f..01c9b60 100644 --- a/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj +++ b/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj @@ -6,6 +6,15 @@ Copyright (c) 2020 Balazs Keresztury MIT 1.0.0-rc0 + true + https://github.com/belidzs/Mailgun.Models.SignedEvent + https://github.com/belidzs/Mailgun.Models.SignedEvent + mailgun api webhook + Implements the data model for Mailgun events to use with custom webhooks. + +This library can be used as a data model for the deserialization of an incoming event data with any JSON serializer of your choice. It even provides a handy function to verify its cryptographic signature. + +Since it targets .NET Standard 1.6 it is compatible with a wide variety of platforms (such as .NET Framework 4.6.1, .NET Core 1.0 and up). diff --git a/README.md b/README.md index 08c8a20..fd6c1bd 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Mailgun.Models.SignedEvent for Mailgun webhooks +# Mailgun.Models.SignedEvent for incoming Mailgun webhooks -Implements the data model for Mailgun events to use with custom webhooks. +Implements the data model for incoming Mailgun events to use with your custom webhooks. This library can be used as a data model for the deserialization of an incoming event data with any JSON serializer of your choice. It even provides a handy function to [verify its cryptographic signature](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks). -Since it targets [.NET Standard 1.6](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) it is compatible with a wide variety of platforms (such as .NET Framework 4.6.1, .NET Core 1.0 and up). +Since it targets [.NET Standard 1.6](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) it is compatible with a wide variety of platforms (such as .NET Framework 4.6.1, .NET Core 1.0 and newer). ## Background @@ -42,14 +42,14 @@ public class DeliveredController : ControllerBase A `SignedEvent` contains a `Signature` and the actual `Event`. While not mandatory it's recommended to check the signature to make sure it was actually signed by Mailgun. -Since the signature is created using the actual timestamp you can specify how old a signature can be to still considered as valid. It is set to 10 minutes by default. +Since the signature is created using the server time you can specify how old a signature can be to still consider as valid. By default this is 10 minutes. ## Important Notes ### Unusual JSON Naming Convention -Mailgun sends JSON data using an unusual naming convention with dashes between words. This means that the verb `is valid` will be encoded as `is-valid` even though the convention is to encode names as *camelCase* (resulting in `isValid`). +Mailgun generates JSON data using an unusual naming convention with dashes between words. This means that the verb `is valid` will be encoded as `is-valid` even though the convention is to encode names as *camelCase* (resulting in `isValid`). There are ways to configure most JSON serializers to handle this, but this topic is out of scope of this project. ### Structure Is Constantly Changing -Please note that these events [can apparently change their structure](https://documentation.mailgun.com/en/latest/api-events.html#event-structure), so don't be surprised if the data you've received doesn't fully correspond to their documentation. If you discover a change (which can only be an addition according to their promise) you're welcome to open a PR. +Please note that these events [can apparently change their structure anytime](https://documentation.mailgun.com/en/latest/api-events.html#event-structure), so don't be surprised if the data you've just received contains new fields. If you discover a change (which can only be an addition according to their documentation) you're welcome to open a PR. From 125510e1ffdd981624c5d3652ada5601a829110d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Keresztury?= Date: Thu, 18 Jun 2020 13:02:25 +0200 Subject: [PATCH 2/4] README modifications Added nuget shield --- README.md | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index fd6c1bd..6f3bd34 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,16 @@ # Mailgun.Models.SignedEvent for incoming Mailgun webhooks -Implements the data model for incoming Mailgun events to use with your custom webhooks. +[![nuget shield](https://img.shields.io/nuget/v/Mailgun.Models.SignedEvent)](https://www.nuget.org/packages/Mailgun.Models.SignedEvent) -This library can be used as a data model for the deserialization of an incoming event data with any JSON serializer of your choice. It even provides a handy function to [verify its cryptographic signature](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks). +Implements data model for incoming Mailgun events to use with your custom Mailgun webhooks. -Since it targets [.NET Standard 1.6](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) it is compatible with a wide variety of platforms (such as .NET Framework 4.6.1, .NET Core 1.0 and newer). +This library can be used as a data model for the deserialization of this data with any JSON serializer of your choice. It even provides a handy function to [verify its cryptographic signature](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks). + +Since it targets .NET Standard 1.6 it is [compatible](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) with a wide variety of platforms (such as .NET Framework 4.6.1, .NET Core 1.0 and newer). ## Background -Mailgun provides *developer friendly* transactional e-mail service. In spite of this claim there's still no official SDK for nearly any platform and their documentation often lacks basic information. However it's still one of the best options you have if you don't want to implement your own e-mail delivery service which can become very complex very quickly. +According to Mailgun they provide *developer friendly* transactional e-mail service. In spite of this claim there's still no official SDK for nearly any platform and their documentation often lacks basic information. However it's still one of the best options you have if you don't want to implement your own e-mail delivery service which can become very complex very quickly. Once you have an account with them you can [subscribe](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks) to various messaging events so when the appropriate event happens (eg. the e-mail was delivered or bounced) Mailgun will POST a JSON encoded object to the URL you provided. @@ -16,8 +18,20 @@ This library was created to ease the burden of deserializing these events into P ## Usage +### Installation + +Add this package as a dependency to your project using [NuGet](https://www.nuget.org/packages/Mailgun.Models.SignedEvent). + +### Example + Here's a practical example using ASP.NET Core 3.1: +```csharp +using Mailgun.Models.SignedEvent; +``` + +... + ```csharp [Route("[controller]")] [ApiController] @@ -26,6 +40,7 @@ public class DeliveredController : ControllerBase [HttpPost] public async Task> PostDelivered([FromBody] SignedEvent signedEvent) { + // ASP.NET Core framework will automagically deserialize JSON into signedEvent (see notes at the bottom regarding caveats) if (!signedEvent.Signature.IsValid("your-api-key")) { // if the signature is invalid, return 401 @@ -42,7 +57,7 @@ public class DeliveredController : ControllerBase A `SignedEvent` contains a `Signature` and the actual `Event`. While not mandatory it's recommended to check the signature to make sure it was actually signed by Mailgun. -Since the signature is created using the server time you can specify how old a signature can be to still consider as valid. By default this is 10 minutes. +Since the signature is created using the signing server's own time you can specify how old a signature can be to still be considered as valid. By default this is set to 10 minutes. ## Important Notes ### Unusual JSON Naming Convention @@ -52,4 +67,6 @@ Mailgun generates JSON data using an unusual naming convention with dashes betwe There are ways to configure most JSON serializers to handle this, but this topic is out of scope of this project. ### Structure Is Constantly Changing -Please note that these events [can apparently change their structure anytime](https://documentation.mailgun.com/en/latest/api-events.html#event-structure), so don't be surprised if the data you've just received contains new fields. If you discover a change (which can only be an addition according to their documentation) you're welcome to open a PR. +Please note that these events [can apparently change their structure anytime](https://documentation.mailgun.com/en/latest/api-events.html#event-structure), so don't be surprised if the data you've just received contains new fields. + +If you discover a change (which can only be an addition according to their documentation) you're welcome to open a PR. From 09ad5a076d422ede34dd67425e100dd11f915e78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Keresztury?= Date: Thu, 18 Jun 2020 13:18:34 +0200 Subject: [PATCH 3/4] Change nuspec --- .../Mailgun.Models.SignedEvent.csproj | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj b/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj index 01c9b60..741a2b4 100644 --- a/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj +++ b/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj @@ -9,12 +9,10 @@ true https://github.com/belidzs/Mailgun.Models.SignedEvent https://github.com/belidzs/Mailgun.Models.SignedEvent - mailgun api webhook - Implements the data model for Mailgun events to use with custom webhooks. + mailgun api webhook email + Implements data model for incoming Mailgun events to use with your custom Mailgun webhooks. -This library can be used as a data model for the deserialization of an incoming event data with any JSON serializer of your choice. It even provides a handy function to verify its cryptographic signature. - -Since it targets .NET Standard 1.6 it is compatible with a wide variety of platforms (such as .NET Framework 4.6.1, .NET Core 1.0 and up). +This library can be used as a data model for the deserialization of this data with any JSON serializer of your choice. It even provides a handy function to verify its cryptographic signature. From 2d483be7b19f8ed9a95a136755b6fcdf5e031eef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Keresztury?= Date: Thu, 18 Jun 2020 13:18:54 +0200 Subject: [PATCH 4/4] Bump version --- Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj b/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj index 741a2b4..a6e935a 100644 --- a/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj +++ b/Mailgun.Models.SignedEvent/Mailgun.Models.SignedEvent.csproj @@ -5,7 +5,7 @@ Balazs Keresztury Copyright (c) 2020 Balazs Keresztury MIT - 1.0.0-rc0 + 1.0.0-rc1 true https://github.com/belidzs/Mailgun.Models.SignedEvent https://github.com/belidzs/Mailgun.Models.SignedEvent