Home

Documentation

How Do Webhooks Work?

In general, Webhooks are a common asynchronous means today for listening to key 'events' raised by online systems, typically over HTTPS.

The idea is simple:

1. Register a callback URL to be called when an "event" of a certain type is going to be raised, and the system will POST you notification of that event (along with any data describing that event) to that callback URL when the event is raised.
2. You first need to register the callback URL with the system for a specific event (which implies a specific DTO of the event data).
3. Sit back and wait to be called at your callback URL.

Under the covers, Webhooks are a good example of pub/sub architectures, where the consumers of the events are (typically) decoupled from the producer of the events.

How will ServiceStack.Webhooks be implemented?

In this project, we are basing the subscription model of webhooks on that defined by GitHub Webhooks.

Which defines the schema and wire representations of subscriptions and published events.

How do I wire-up ServiceStack.Webhooks to my services?

In this project, you will add webhooks to your ServiceStack project, by registering (and customizing) the WebhookFeature in your AppHost.cs

public override void Configure(Container container)
{
    Plugins.Add(new WebhookFeature
    {
...your configuration
    });
}

In this project, we are going to provide an API that stores subscriptions in a built-in 'Webhooks' service that will be hosted your service (the one that registers the WebHookFeature plugin). That service will allow users of your API to create, list, update and delete subscriptions to events that your service raises.

In this project, the IWebhookPublisher singleton, will publish an event (IWebhookPublisher.Publish<TDto>(string event, TDto data)) to a central store (i.e. DB, queue, etc), and a IWebhookRelay.NotifySubscribers() will relay the stored event to all registered subscribers at that time.

The publisher and the relay are likely to be (depending on how you configure the WebhookFeature decoupled from each other, and in some cases run in different networks/clouds etc.

Extensibility

There are several points of extensibility in this implementation:

• How and where to store subscriptions (i.e DB, Memory, etc) in the configured IWebhookSubscriptionStore Component
• How and where to store published events (i.e. DB, queue, cloud function) in the configured IWebhookEventStore Component
• How to relay events to subscribers (i.e. In a Cloud function, in-process function, worker role, scheduled process etc.) in the configured IWebhookRelay Component

Installation

In this project, there can be (depending on the community contribution) several nuget packages that need to deliver each of these components depending on the architecture requirements of your service.

• The nuget package 'Servicestack.Webhooks' will provide the WebhookFeature and subscription service, and IWebhook implementation. It may also provide an in-process InProcWebhookRelay for relaying events from the service that raised them (stored in Memory/DB).
• The nuget package 'Servicestack.Webhooks.Interfaces' (included in all other packages) will provide all the definitions of all the services and key DTO's involved in all layers of the architecture.
• The nuget package 'Servicestack.Webhooks.Azure' (for example) would provide IWebhookEventStore as an Azure queue, and a AzureQueueWebhookRelay For relaying queued events to subscribers