Subscription Service

The WebhookFeature plugin automatically installs a (secure) subscription management API into your AppHost

This allows any users of your web service to create webhook registrations (subscribers to webhook events) for any event that you raise from any of your services, and it allows relays to raise events to subscriber endpoints.

The following routes are added to your AppHost:

• POST /webhooks/subscriptions - creates a new subscription (for the current user)
• GET /webhooks/subscriptions - lists all subscriptions (for the current user)
• GET /webhooks/subscriptions/{Id} - gets the details of the subscription
• PUT /webhooks/subscriptions/{Id} - updates the subscription
• DELETE /webhooks/subscriptions/{Id} - deletes the subscription
• GET /webhooks/subscriptions/search - gets the subscribers for a specific event
• PUT /webhooks/subscriptions/history - adds tracking of events raised to subscribers (i.e. the StatusCode and StatusDescription returned by the subscriber endpoint)

Note: Webhook subscriptions will be associated to the UserId (ISession.UserId) of the user using your service, only if you have added the AuthFeature to your AppHost configuration.

Note: This service uses role-based authorization to restrict who can call what, and you can customize those roles, only if you have added the AuthFeature to your AppHost configuration.

Creating A Subscription

A subscriber creates a subscription by POSTing the following data:

POST /webhooks/subscriptions
{
    name: "My Webhook",
    events: ["hello", "goodbye"],
    config: {
        url: "http://myserver/api/incoming",
        content-type: "application/json",  (optional)
        secret: "ASUPERSECRETKEY",  (optional)
    }
}

Note: a subscriber can subscribe to more than one event at a time, as well as subscribe to any number of events.

Note: A duplicate subscription with the same event name and same URL is not permitted.

Customizing the Subscription Service

The SubscriptionService is automatically built-in to your ServiceStack AppHost when you add the WebhookFeature.

If you prefer to disable the built-in one or roll your own subscription service, you can turn-off the built-in one like this:

public override void Configure(Container container)
{
   // Add other plugins first

    Plugins.Add(new WebhookFeature
    {
        IncludeSubscriptionService = false
    });
}

Security

By default, the operations of the subscription service are secured by role-based access. And this access is only activated if you already have the AuthFeature plugin added in your AppHost.

WARNING: If you don't use the AuthFeature then the subscription service will not be secured, and can be used by anyone with access to your API.

Note: If you use the AuthFeature, remember to add the WebhookFeature plugin after you add the AuthFeature plugin.

When the subscription service is secured, by default, the following roles are protecting the following operations:

• POST /webhooks/subscriptions - "user"
• GET /webhooks/subscriptions - "user"
• GET /webhooks/subscriptions/{Id} - "user"
• PUT /webhooks/subscriptions/{Id} - "user"
• DELETE /webhooks/subscriptions/{Id} - "user"
• GET /webhooks/subscriptions/search - "service"
• PUT /webhooks/subscriptions/history - "service"

These arbitrary roles are the defaults, and they are easily configurable to be your own roles by setting the following properties of the WebhookFeature when you register it:

public override void Configure(Container container)
{
    // Add the AuthFeature plugin first
    Plugins.Add(new AuthFeature(......);

    Plugins.Add(new WebhookFeature
    {
        SecureSubscriberRoles = "subscriber;Admin",
        SecureRelayRoles = "relay"
    });

}

Note: You can even set the SecureSubscriberRoles or SecureRelayRoles to null if you don't want to use role-based access to secure those specific service operations.

Subscription Store

Subscriptions for webhooks need to be stored (in a ISubscriptionStore), once a user of your service subscribes to a webhook (using the API: POST /webhooks/subscriptions)

You specify your own store by registering it in the IOC container (before adding the WebhookFeature to your AppHost).

WARNING: If you specify no store, the default MemorySubscriptionStore will be used, which is fine for testing, but beware that your subscriptions will be lost whenever your service is restarted.

public override void Configure(Container container)
{
    // Register your own subscription store
    container.Register<ISubscriptionStore>(new MyDbSubscriptionStore());

    Plugins.Add(new WebhookFeature();
}