deveel.webhooks

Deveel Webhooks

Этот проект предоставляет набор инструментов .NET для управления подписками на события, базовые преобразования и уведомления о таких событиях ( WebHooks ): в глобальном проектном объеме эта модель позволяет управлять событиями архитектуры, запуская системные процессы при возникновении ожидаемых случаев от других систем.

Хотя эта модель интеграции широко используется крупными поставщиками услуг (например, Sendgrid , Twilio , Github , Slack и т. Д.), Не существует формального протокола или полномочий, которые обеспечат соблюдение соответствия (например, для других случаев, таких как OpenID, OpenAPI и т. Д.).

В любом случае, типичная реализация состоит из следующих элементов:

• Webhooks транспортируются через обратные вызовы HTTP
• Полезная нагрузка Webhook форматируется как объект JSON (или, в качестве альтернативы, в меньших распространенных сценариях, как XML или форма)
• Полезная нагрузка Webhook включает в себя свойства, которые описывают тип события и временной маршрут происшествия
• Дополнительная подпись в заголовке запроса или параметр строки запросов гарантирует подлинность вызывающего абонента

Я пытался выразить концепции более подробно на этой странице в этом репозитории (без каких -либо амбиций быть педагогическими).

Библиотеки структуры

Библиотеки, в настоящее время предоставленные структурой, являются следующими:

Библиотека	Nuget	GitHub (prerelease)
Deveel.Webhooks
Deveel.webhooks.sender
Deveel.webhooks.service
Deveel.webhooks.mongodb
Deveel.webhooks.entityframework
Deveel.webhooks.dynamiclinq
Deveel.webhooks.receiver.aspnetcore

Следующие библиотеки расширяют структуру с приемниками для конкретных поставщиков:

Библиотека	Nuget	GitHub (prerelease)
Deveel.webhooks.receiver.twilio
Deveel.webhooks.receiver.sendgrid
Deveel.webhooks.receiver.facebook

Вы можете получить стабильные версии этих библиотек из официального канала Nuget.

Чтобы получить последние предварительные версии пакетов, вы можете восстановить у диспетчера пакетов DeVeel.

Документация

Мы хотели бы помочь вам начать работу с этой структурой и в конечном итоге расширить ее: пожалуйста, обратитесь к разделу документации или к официальному веб -сайту , который мы создали для вас.

Самый простой способ начать - следовать руководству по началу работы , но вы также можете обратиться к разделу «Часто задаваемые вопросы» , чтобы получить ответы на самые распространенные вопросы.

Мотивация

Работая над проектом .NET CORE 3.1/.NET 5 PAAS ( платформ-как-услуга ), который функционально требовал возможности пользователей службы способным создавать подписки на систему в систему и уведомления о событиях через HTTP-канал (который обычно называется Web-Hooks , или HTTP Callcks ), я начал свой дизайн, чтобы использовать существующие растворы, чтобы избежать оборудования, но вовремя возобновить, но я убедил, что у меня есть наполосы , но мы запланировали, но вовремя возобновить Разочаровано в таких амбициях:

• Проект Microsoft ASP.NET Webhooks был заархивирован и вернулся обратно в Microsoft ASP Labs (который не имеет видимости в его выпуске), нацеленного на один день, чтобы обеспечить совместимость с ядром .NET (которое в конечном итоге развивалось, став LTS)
• Оба проекта Microsoft (The Legacy и Experimental ) не совместимы с последними стеками .NET ( .NET 5 / .NET 6 )
• Экспериментальные проекты Microsoft никогда не реализовали каких -либо возможностей обработки подписок и в конечном итоге удалили возможность отправителя , сосредоточившись исключительно на приемниках
• Альтернативные реализации, обеспечивающие аналогичные возможности, являются встроенными и органическими частями более крупных рамок (например, ASP.NET Boilerplate), которые заставили бы меня принять все такие рамки, помимо моих намерений дизайна

Простой пример использования

Документация структуры предоставит вам более подробную информацию о требованиях, конфигурациях, использовании и расширении структуры.

В любом случае, чтобы помочь вам начать работу с фреймворком, пожалуйста, рассмотрите следующие примеры, которые показывают, как создать простую службу управления веб -хук, которые обрабатывают подписки и уведомления, а также получатель клиента.

Подписки и уведомления

В качестве поставщика услуг эта библиотека предоставляет функции для обработки двух основных аспектов шаблона веб -крюка:

• Подписки : возможность клиента подписаться на конкретное событие, предоставляя конечную точку, которая должна быть уведомлена
• Уведомления : возможность сервера отправлять уведомления в подписанные конечные точки

В следующем примере показано, как создать подписку WebHook и как отправить уведомление в конечные точки абонента:

 using Microsoft . AspNetCore . Builder ;

using Deveel . Webhooks ;

namespace Example {
    public class Program {
        public static void Main ( string [ ] args ) {
            var builder = WebApplication . CreateBuilder ( args ) ;
            
            // ...

            builder . Services . AddWebhookSubscriptions < MongoWebhookSubscription > ( subs => { 
                subs . UseMongoDb ( "mongodb://localhost:27017" )
                    . UseSubscriptionResolver ( ) ;
            } ) ;
				
            builder . Services . AddWebhookNotifier < MyWebhook > ( notifier => {
                notifier . UseSender ( sender => {
                   sender . Configure ( options => {
                        options . Timeout = TimeSpan . FromSeconds ( 30 ) ;
                   } ) ;
               } ) ;
            } ) ;

            var app = builder . Build ( ) ;

            // ...

            // ... and notify the receivers manually ...
            app . MapPost ( "/webhooks" , async ( HttpContext context , 
                [ FromServices ] IWebhookSender < MyWebhook > sender , [ FromBody ] MyWebhookModel webhook ) => {
                var destination = webhook . Destination . ToWebhookDestination ( ) ;
                var result = await sender . SendAsync ( destination , webhook , context . HttpContext . RequestAborted ) ;

                // ...

                return Results . Ok ( ) ;
            } ) ;

            // ... or notify the webhooks automatically from subscriptions
            app . MapPost ( "/webhooks/notify" , async ( HttpContext context , 
                [ FromServices ] IWebhookNotifier < MyWebhook > notifier , [ FromBody ] MyEventModel eventModel ) => {
                var eventInfo = eventModel . AsEventInfo ( ) ;
                var result = await notifier . NotifyAsync ( eventInfo , context . HttpContext . RequestAborted ) ;

                // you can log the result of the notification to all receivers ...
                return Results . Ok ( ) ;
            } ) ;

            app . Run ( ) ;
        }
    }
} 

Приемники

Структура также предоставляет набор встроенных приемников, которые можно использовать для обработки входящих уведомлений из подписанных конечных точек в вашем приложении.

В следующем примере показано, как создать приемник для веб -крючка, который поддерживается сообщением Facebook Messenger:

 namespace Example {
    public class Program {
        public static void Main ( string [ ] args ) {
            var builder = WebApplication . CreateBuilder ( args ) ;
            
            // ...

            builder . Services . AddFacebookReceiver ( )
                . AddHandler < MyFacebookWebhookHandler > ( ) ;

            var app = builder . Build ( ) ;

            // ...

            // ... you can handle all the incoming webhooks at "/webhooks/facebook"
            // invoking all the handlers registered in the service collection ...
            app . MapFacebookWebhook ( "/webhooks/facebook" ) ;

            // ... or you can handle the incoming webhooks manually ...

            app . MapFacebookWebhook ( "/webhooks/facebook2" , async ( FacebookWebhook webhook , IService service , CancellationToken ct ) => {
                // ...
                await service . DoSomethingAsync ( webhook , ct ) ;
            } ) ;

            app . Run ( ) ;
        }
    }
} 

Способствовать

Взносы в проекты с открытым исходным кодом, такие как DeVeel Webhooks , обычно обусловлены интересом к использованию продукта и услуг, если они будут уважать некоторые из ожиданий, которые мы имеем для его функций.

Лучшие способы внести свой вклад и улучшение качества этого проекта-это пробовать его, задать проблемы, присоединиться к дизайнерским разговорам и делать запросы.

Пожалуйста, обратитесь к руководящим принципам, чтобы получить более подробную информацию о том, как вы можете внести свой вклад в этот проект.

Мы стремимся ответить на большинство вопросов, которые у вас могут возникнуть, предоставив документы, отвечая на часто задаваемые вопросы и следуя таким вопросам, как отчеты об ошибках и запросы функций.

Участники

Информация о лицензии

Этот проект выпущен в соответствии с соглашением о лицензировании Apache 2 с открытым исходным кодом.