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.

Subscribing to Events

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.

Consuming Events

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: mysubscriber
Content-Length: 26
Expect: 100-continue
Proxy-Connection: Keep-Alive

{
    "Text": "I said hello"
}

Then you might 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' in response to this event, or any of these: '200 - OK', '202 - Accepted' or '204 - No Content' response (any 2XX or 3XX statuscode is acceptable).

Note: If your subscriber service returns any a 4XX or 5XX statuscode, your webhook subscription will probably be automatically disabled, and no more events will be POSTed to it. This is the normal policy for subscribers (by relays), since 4XX or 5XX indicates an endpoint that is either incorrectly configured (4XX) or broken/unreachable (5XX). (You can see that policy implemented in the Relay method)

Metadata

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 as a unique identifier (or correlation ID) and for example, used to prevent replay attacks.

The X-Hub-Signature header is described in Subscriber Security