Webhook (v2)
Description
The Webhook trigger allows a HTTP request to initiate a Flow defined in Extension Kit Portal. In a typical scenario this trigger would be utilized to allow a workflow defined somewhere else to continue execution in a U4EC Flow. More details are available for such a scenario at Appendix A: LogicApps.
Basic Configuration
An unique descriptive name needs to be provided for a Webhook trigger.
Authentication
Optionally the endpoint can be secured, using one of the following authentication method.
NOTE: If you do not want to secure your enpoint, select
None
in the authentication options.
Basic
An User name and a Password needs to be specified. When calling this endpoint, an authentication header needs to be provided as described at the following link
U4IDS (connected)
When calling an endpoint that is secured by U4IDS, a token has to be sent in the authorization header, that is obtained from U4IDS. Optionally some claims can be requested to be present in the token. When setting up such claims, in the values we can use the macros {{triggerId}}
and {{tenant}}
, they will be replaced with their actual values automatically.
Azure Active Directory
When calling an endpoint that is secured by U4IDS, a token has to be sent in the authorization header, that is obtained from Azure Active Directory. Optionally some claims can be requested to be present in the token. When setting up such claims, in the values we can use the macros {{triggerId}}
and {{tenant}}
, they will be replaced with their actual values automatically.
Request Body
Webhook's payload can be specified in this section. The dropdown menu allows to specify the content type of it:
- JSON: This is the default option. An schema can be set up and it will be shown in trigger's config.
- XML: Flow will accept XML as payload, no schema needed.
- Text: Flow will accept text as payload, no schema needed
Primary response
Response from Webhook can be customized. There are two configuration sections to customize the response. Primary Response configuration allows the user to configure the response to POST requests.
-
Status Code: by default Webhook responds with 204 No Content code. It can be changed to respond with 200 OK or 202 Accepted.
-
Headers: response can include custom headers specifying key and value for each one.
-
Body: response can include a custom body response.
Secondary response
Additional verbs can be added to Webhook V2 response under the Secondary Response section. The supported methods are OPTIONS, GET and PUT. If the webhook is called with a method that is not configured the response will be 405 - Method not allowed. The rest of the parameters are the same than Primary Response configuration.
Even though Webhook V2 supports both primary and secondary response configurations, only POST requests trigger the flow. OPTIONS, GET and PUT requests are meant to be used for validating subscription systems such as Event Grid.
Templating system
Webhook supports templating system to use the incoming request to build a custom response. Supported templates are:
-
Query: following expression
{{step0.request.query[QueryKey]}}
will be replaced by the value of the query parameter if present in the incoming request. -
Header: following expression
{{step0.request.header[Header]}}
will be replaced by the value of the header if present in the incoming request. -
Body: following expression
{{step0.request.body.propertyPath}}
will be replaced by the value of the payload if present in the incoming request. It supports simple/deep properties and array values.
Example: Subscribe Extension Kit Flow to EventGrid
Custom response in conjunction with templating system can be used to validate event source subscriptions. It means that a Extension Kit Flow can be subscribed to a event source so it will be triggered when new events occurs in the source.
Following configuration can be used to subscribe a Flow to Event Grid with Cloud Event Schema v1.0.
Input
The request that is posted to the endpoint.
Output
The original input received including headers, query and body.
Custom data
After saving a flow that uses the Webhook trigger, the system will generate 2 URI's. The first one, Address is the URI to which the data needs to be pushed by the external application. The second one, Metadata Address provides an endpoint that returns the metadata in Swagger / OpenAPI format. This metadata address can be provided for example when using the Logic App's Http + Swagger connector.
NOTE: Custom data will be cleared if the flow is disabled or trigger is updated.
Advanced configuration - Mutual TLS
Mutual TLS, also known as mTLS or 2-way SSL, is a technique for two-way authentication. mTLS ensures that the parties at each end of a connection are who they claim to be. The information within their respective TLS certificates provides additional verification.
In order to enable mTLS for the Extension Kit Webhook trigger, access the Webook Trigger> Advanced configuration> Client Certificate and select your certificate of choice. For more information regarding certificates and how to add a new one, please refer to the certificates documentation.
Please notice that a flow that is being triggered with an expired certificate, or whose validity has not yet started, will not run. Additionally, a Flow being activated by a certificate that does not match with the webhook setup will not run as well.
WARNING: Incoming webhook calls must be comprised of their certificate and respective private key. The private key is not saved or stored and does not reach the Extension Kit area. It is only used to guarantee the ownership of the matching inbound certificate during the process.