Webhooks

eShopOnContainers supports using webhooks to notify external services about events that happened inside eShopOnContainers. A new API and a webhooks demo client were developed.

CONTENT

• Webhooks API
  • Registering a webhook
• Webhooks client

Webhooks API

Webhooks API is exposed directly (not through any BFF) because its usage is not tied to any particular client. The API offers endpoints to register and view the current webhooks. The API is authenticated, so you can only register a new webhook when authenticated in the Identity.API and when you list the webhooks, you only see the webhooks registered by you.

Registering a webhook

Registering a webhook is a process that involves two parties: the Webhooks API and the Webhooks client (outside eShopOnContainers). To avoid allowing clients that aren't under your control a basic security mechanism (known as URL Granting) is used when registering webhooks:

• When registering the webhook (using Webhooks API under authenticated account) you must pass a token (any string value up to you) and a "Grant URL".
• Webhooks API will call the "Grant URL" using HTTP OPTIONS and passing the token sent by you in the X-eshop-whtoken header.
• Webhooks API expects to receive a HTTP successful status code and the same token in the same x-eshop-whtoken header, in the response

If token is not sent in the response, or the HTTP Status code is not successful, then the Webhooks API, returns a HTTP Status Code 418 (because trying to register a URL owned by someone else is almost the same as making coffee in a teapot ;-)).

Due to security reasons the "Grant URL" used and the URL for the webhook MUST belong to the same

When eShopOnContainers sends the webhook, this token is also sent (in the same header), giving the client the choice to process or not the hook.

Webhooks client

Webhooks Client is a basic web (developed with Razor Pages) that allows you to test the eShopOnContainers webhooks system. It allows you to register the "OrderPaid" webhook.

The client is exposed directly (like all other clients). In k8s the ingress path is /webhooks-web.

Here are the configuration values of this demo client (with the values used in default compose file):

- ASPNETCORE_URLS=http://0.0.0.0:80
- Token=6168DB8D-DC58-4094-AF24-483278923590      # Webhooks are registered with this token
- IdentityUrl=http://10.0.75.1:5105
- CallBackUrl=http://localhost:5114
- WebhooksUrl=http://webhooks.api
- SelfUrl=http://webhooks.client/

• Token: Client will send always this token when webhooks asks for url grant. Also client expects this token to be in the webhooks sent by eShopOnContainers.
• IdeneityUrl: URL of Identity API
• CallBackUrl: Callback url for Identity API
• WebhooksUrl: URL of webhooks API (using internal containers networking)
• SelfUrl: URL where demo client can be reached from webhooks api. In k8s deployments ingress-based url is used, in compose the internal url has to be used.

There is an additional configuration value named ValidateToken. If set to true (defaults to false), the webhook demo client ensures that the webhook sent by eShopOnContainers has the same token as the Token configuration value. If set to false, the client will accept any hook, regardless its token header value.

Note: Regardless the value of ValidateToken configuration entry, note that the client always sends back the value of Token entry when granting the url.