ayan.poddar/eShopOnContainers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Created 17. Using Webhooks in eShopOnContainers (markdown)

Eduard Tomàs 2019-02-11 12:07:33 +01:00
parent 3eba3e3bc7
commit f8a9bd3b14
1 changed files with 48 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
17.-Using-Webhooks-in-eShopOnContainers.md Normal file

@ -0,0 +1,48 @@
# Using Webhooks in eShopOnContainers
eShopOnContainers supports using _webhooks_ to notify external services about events that happened inside eShopOnContainers. A new API and a webhooks demo client were developed.
## 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):
```yaml
- 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**.