Add Webhooks to your ServiceStack services

Overview

This project makes it very easy to expose webhook notifications from your ServiceStack services, and helps you manage your user's subscriptions to those webhooks.

By adding the WebhookFeature to the AppHost of your service, you automatically get all the pieces you need to raise and manage the events raised by your services.

We know that most services are built for scalability and to be hosted in the cloud, so we know that you are going to want to use your own components and technologies that fit in with your own architecture. All you have to do is plug into the WebhookFeature.

For example: In one service, you may want to store the Webhook subscriptions in a MongoDB database, and have an Azure worker role relay the events to subscribers from a (reliable) cloud queue.

In another service, you may want to store subscriptions in Ormlite SQL database, and relay events to subscribers directly from within the same service on a background thread, or throw the event to an AWS lambda to process. Whatever works for you, the choice is yours.

Oh, don't worry, getting started is easy. We got your back with a built-in subscription store and built-in event sink that will get you going seeing how it all works. But eventually you'll want to swap those out for your own pieces that fit your architecture, which is dead easy.

If you cant find the component you want for your architecture (see Plugins), it should be easy for you to build add your own and just plug it in.

Getting Started

Install from NuGet:

Install-Package ServiceStack.Webhooks

Simply add the WebhookFeature in your AppHost.Configure() method:

public override void Configure(Container container)
{
    // Add ValidationFeature and AuthFeature plugins first

    Plugins.Add(new WebhookFeature());
}

See Getting Started for more details.

Raising Events

To raise events from your own services:

1. Add the IWebhooks dependency to your service
2. Call: IWebhooks.Publish<TDto>(string eventName, TDto data)

As simple as this:

internal class HelloService : Service
{
    public IWebhooks Webhooks { get; set; }

    public HelloResponse Any(Hello request)
    {
        Webhooks.Publish("hello", new HelloEvent{ Text = "I said hello" });
    }
}

Subscribing to Events

Subscribers to events raised by your services need to create a webhook subscription to those events.

They do this by POSTing something like the following, to your service:

POST /webhooks/subscriptions
{
    "name": "My Webhook",
    "events": ["hello", "goodbye"],
    "config": {
        "url": "http://myserver/api/incoming",
    }
}

Consuming Events

To consume events, a subscriber needs to provide a public HTTP POST endpoint on the internet that would receive the POSTed webhook event.

The URL to that endpoint is defined in the config.url of the subscription (above).

In the case of the "hello" event (raised above), the POSTed event sent to the subscriber's endpoint might look something like this:

POST http://myserver/hello HTTP/1.1
Accept: application/json
User-Agent: ServiceStack .NET Client 4.56
Accept-Encoding: gzip,deflate
X-Webhook-Delivery: 7a6224aad9c8400fb0a70b8a71262400
X-Webhook-Event: hello
Content-Type: application/json
Host: myserver
Content-Length: 26
Expect: 100-continue
Proxy-Connection: Keep-Alive

{
    "Text": "I said hello"
}

To consume this event with a ServiceStack service, the subscriber would standup a public API like the one below, that could receive the 'Hello' event. That might have been raised from another service with a call to Webhooks.Publish("hello", new HelloEvent{ Text = "I said hello" }):

internal class MyService : Service
{
    public void Post(HelloDto request)
    {
        // They said hello!
        var message = request.Text;

       
        // The event name, messaging metadata are included in the headers
        var eventName = Request.Headers["X-Webhook-Event"];
        var deliveryId = Request.Headers["X-Webhook-Delivery"];
        var signature = Request.Headers["X-Hub-Signature"];
    }
}

[Route("/hello", "POST")]
public class HelloDto
{
    public string Text { get; set; }
}

Note: Webhook events can be delivered securely to subscribers using signatures, that proves the authenticity of the sender only. Delivered events are never encrypted, and only signed. See Subscriber Security for more details.

Documentation

More documentation about how the WebhookFeature works, and how to customize it are available in here

Contribute?

Want to get involved in this project? or want to help improve this capability for your services? just send us a message or pull-request!