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 subscription service interface, and wire representations of published events.

• Subscription Service Definition (except ping)
• Event Payloads

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)
{
    // Register the ValidationFeature and AuthFeature first
    Plugins.Add(new ValidationFeature());
    Plugins.Add(new AuthFeature(...));

    // Register your own IWebhookSubscriptionStore and IWebhookEventSink
    container.Register<IWebhookSubscriptionStore>(new MyDbSubscriptionStore());
    container.Register<IWebhookEventSink>(new MyAsyncEventSink());

    Plugins.Add(new WebhookFeature
    {
        .. any customization for your environment
    });
}

WARNING: In any production system you are going to need to register your own IWebhookSubscriptionStore and IWebhookEventSink, since the built-in ones are really only designed for getting up and running quickly, and for testing.

See Getting Started for more details

What does the WebhookFeature do?

The WebHookFeature installs the following things into your service:

1. A singleton IWebhooks service that you can use in your services to raise events as they happen, using the Publish<TDto>(string eventName, TDto data).
2. A full SubscriptionsService service that provides all the operations for your subscribers to manage their own webhook registrations.

How can I extend the WebhookFeature to suit my architecture?

There are several points of extensibility in the WebhookFeature, and each may support their own customization:

WebhookFeature

BY default the WebHookFeature registers and configures the SubscriptionService to provide an API for subscribers to manage their webhooks.

You can choose to turn this service off, and even ship your own, and you can also configure the authorization roles that secure it.

See WebhookFeature for more details on how to customize it.

Subscription Service

By default, the built-in SubscriptionService is secured like all other services in your ServiceStack AppHost (using the AuthFeature), and it uses role-based authorization to secure the various operations.

You can, if you choose customize the roles these operations require.

See Subscription Service for more details on how to customize it.

Subscription Store

By default, the built-in MemoryWebhookSubscriptionStore uses an MemoryCacheClient store for storing subscriptions.

You should register a different IWebhookSubscriptionStore that will persist subscriptions to some permanent (and perhaps distributed) store in your architecture. These stores are typically provided by extensions to the ServiceStack.Webhooks framework such as those listed in: Plugins

WARNING: The MemoryWebhookSubscriptionStore is not designed for use in production systems. If you do NOT register your own IWebhookSubscriptionStore your subscriptions will be lost when your AppHost restarts!

Event Sink

By default, the built-in AppHostWebhookEventSink will relay events to all subscribers in the same thread that called IWebhooks.Publish<TDto>().

You should register a different IWebhookEventSink that will decouple the raising of events from the relays of events to subscribers, using appropriate components in your architecture. (i.e. muti-threading, queues, async hooks etc.)

These kinds of sinks are typically provided by extensions to the ServiceStack.Webhooks framework such as those listed in: Plugins

WARNING: The AppHostWebhookEventSink is not designed for use in production systems. If you do NOT register your own IWebhookEventSink your services will suffer unacceptable performance penalties.