Subscription Service

The WebhookFeature plugin automatically installs a (secure) subscription management API into your AppHost on the following routes:

• 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

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.

Note: Webhook subscriptions will be associated to the UserId (ISession.UserId) of the user using your service.

Note: This service uses role-based authorization to restrict who can call what, and you can customize those roles. (see later)

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.

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 service when you add the WebhookFeature.

If you prefer to 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 subscription service is secured by role-based access. And this is activated if you already have the AuthFeature plugin added in your AppHost.

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"

These roles are configurable 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
    {
        SubscriptionAccessRoles = "accessrole1",
        SubscriptionSearchRoles = "searchrole1;searchrole2"
    });

}

Note: You can even set the SubscriptionAccessRoles or SubscriptionSearchRoles to null if you don't want to use role-based access to secure those 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).

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();
}