Subscribing

Subscribers to webhook events raised by your services will need to:

1. Creating an public internet endpoint to received the webhook event.
2. Create a webhook subscription to those events, configured with the URL of the public internet endpoint. (by calling POST /webhooks/subscriptions)
3. Handle the POSTed request in the public internet endpoint, and do whatever they like with the event and the specific event's data.

Creating a subscription

To subscribe to a webhook, Install-Package ServiceStack.Webhooks.Interfaces, and POST the following, to the subscription service:

var client = new JsonServiceClient("https://myservice/api");
            client.Post(new CreateSubscription
            {
                Name = "My Webhook",
                Events = new List<string> {"hello", "goodbye"},
                Config = new SubscriptionConfig
                {
                    Url = "http://mysubscriber/hello"
                }
            });

Which sends the following on the wire:

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

Where 'hello' and 'goodbye' are the names of the published events raised by that service. Where the config.url is a public internet endpoint that handles the event when it is raised.

Security

By providing a config.secret in the registration, you can request that events are raised to your service securely.

POST /webhooks/subscriptions
{
    "name": "My Webhook",
    "events": ["hello", "goodbye"],
    "config": {
        "url": "http://mysubscriber/hello",
        "secret": "mybase64encodedsecret"
    }
}

See Subscriber Security for more details.

Creating an endpoint

Now you will need to create a public internet endpoint to receive the webhook event when it is fired.

Let's say that the 'hello' event that you subscribed to looked like this:

POST http://mysubscriber/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"
}

Then you would create a subscriber service that looked something like this:

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

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

You would normally return a '201 - Created', or any of these: '200 - OK', '202 - Accepted' or '204 - No Content' response (any 2XX or 3XX statuscode is acceptable).

Notice that the incoming message also includes a X-Webhook-Delivery and X-Webhook-Event headers.

The X-Webhook-Event value is the name of the event that was raised.

The X-Webhook-Delivery value can be used (for example) as a unique identifier to prevent replay attacks.