HTTP Endpoints

Custom WebHooks into your application

Custom HTTP Endpoints are currently (June 2022) only available in Private Cloud Runtime environments. Not (yet) in the standard Public Shared Cloud.

So, while you can already define your Custom HTTP Endpoints in the Modeler for your Project, they will only actually work when your portals are running on a Private Cloud Runtime!

What are Custom HTTP Endpoints?

With these Custom HTTP Endpoints, WEM provides yet another way to make integration with other applications possible. Other integration features available are SOAP/XML, REST/JSON, OData, SAML, OAuth and information about those features can be found in the Services and Integration section.

HTTP Request Messages can be sent using different methods [wiki]. Other applications may be able to send those messages in order to get information out of your WEM Portal or make changes to your data.

Create HTTP Endpoint

Please make sure that wherever you can enter names for parameters, you use URL-Safe characters (read this post on stackoverflow).

In Tab Navigation, element HTTP Endpoints, click the [...] button to open the context-menu and click New HTTP Endpoint.

Endpoint Configuration options

URL Path

The URL Path is a templated path containing literal (fixed) parts and parameter (dynamic, replaceable) parts. The hostname part is automatically implied for each portal and all the configured hostnames published to the runtimes, so in this field you only have to enter the path that starts after the hostname:

https://portal.wem.io/CUSTOM_URLPATH.

Parameters are surrounded by curly brackets: {parameter}. In the example below {order-id} is a parameter part named order-id as part of the URL-Path.

Example: order/get/{order-id}

Parameters can be bound to a target data field. As soon as you type a parameter part {curly-brackets-with-parameter-name} , the name between the curly brackets will automatically be added to the list of Parameters for the URL Path. At runtime, when the path is requested, the value at the position of the parameter will be written to the target data field as defined in this part.

Query Parameters can also be added in the Parameters section, to add additional parameters that will become part of the additional query string. The Query String is the part in the URL that starts with a question mark ? and is followed by name=value pairs, separated by an & ampersand. A Query string is considered not as a part of the URL Path itself, but as an addition to the request to said path. The path defines the resource (location), the query string adds elements for specific logic on or within that resource.

HTTP Request Method

The HTTP Request Method (wiki) indicates the method (or verb) of the HTTP request expected by the endpoint. If this is set to “None” then the endpoint does not accept any request on this specific path. Endpoints with a “None” method are used as part of other endpoints.

• GET: request to retrieve data without making changes in the portal;

• POST: request body is required with payload (data) that may trigger changes in the portal;

• DELETE: request to delete the indicated resource;

• HEAD: request to retrieve only the header information for a request (no response body); used for checking availability of a resource or content-length of a file

• OPTIONS: request to provide the HTTP methods that the portal supports;

• PATCH: request to perform a partial update with the provided information in the request body;

• PUT: request to create or update a resource with the information provided in the request body;

• None: to indicate that this path will not accept requests to this specific path, but it may be used as a (re-usable) part for other endpoints

Validate parameters automatically

If this option is checked and any validation error occurs, an exception is thrown and the request is not further handled.

Some validation errors:

• Missing request body (required for methods POST, PUT and PATCH);

• Missing required parameter value;

• Multiple values provided for a parameter;

• Value conversion error. The raw value could not be converted to the expected datatype of the data field;

• Value out of range error. For example, integer value falls out of allowed range of the numeric data field.

• Value format error. For example, if raw value does not conform to the format of a valid email address.

By disabling this option, the endpoint will continue with the flow, but the mapped fields may not have valid values (so you may need to perform your own checks and validations additionally).

Initiate a WEM Runtime Session on first request

This option indicates if a WEM Session should be used when this endpoint is targeted.

FALSE (no WEM Session)

Typically used for API integration, like REST/JSON: basically 2 applications exchanging messages/data in a single interaction. There is no session required, no specific user, no specific process with consecutive steps that need the data from the first interaction onwards.

TRUE (requires WEM Session)

Typically used in WEB-HOOK situations.

When a user (via browser) is already active in the Portal (active session), or if a new session should be started and the provided data in the request should be used and made available in consecutive steps, so you want to be able to continue in the Portal with the externally triggered changes.

One typical example is when using external payment providers, that typically prescribe a certain Web-Hook they use to send the transaction results, you want to retrieve that and link it specifically to the active session.

Parse form fields in request body to JSON

This option becomes available when the selected HTTP Request Method is one that requires a Request Body: POST, PATCH, PUT.

If this option is enabled, the form-fields within the request body will be converted into a JSON structure, making it easy to use the Import JSON Node to map these form-field-values to WEM-Fields in the Data Model. The conversion will be executed to BEST-EFFORT. The providing application may provide form-fields in a way that is not easily correctly converted into JSON, especially when they use custom ways to group multiple fields (array/indexed).

Request Body Content

This option becomes available when the selected HTTP Request Method is one that requires a Request Body: POST, PATCH, PUT.

Put a Data Field into this input to map the contents of the Request Body (from the POST, PATCH or PUT request). This field can be Text (for form-fields, json, or other text contents) or a File (to exchange binary files - directly map them from and to WEM File Fields).

OpenAPI Documentation

WEM can automatically generate OpenAPI Documentation for your custom HTTP Endpoints. The resulting OpenAPI documentation can be accessed when the Custom HTTP Endpoints are available in the Staging or Live runtime environments (so after publishing), by using the following link:

{your-portal-hostname}/openapi

This url or its resulting JSON can be used in other applications that can visualize or generate client code based on OpenAPI documentation. Swagger is a well-known tool to visualize this information.

In this part you can provide additional information that the OpenAPI documentation will provide.

Endpoint name

Name used in the OpenAPI document generated for the endpoint. This name is used as method/function identifier by tools generating client code for calling this endpoint.

Description

This description is included in the OpenAPI document generated for the endpoint. With this description you can provide further detailed information about your custom endpoint to the consuming party.

Parameters

Source column indicates in which Request-element the parameter is located: URL Path, Query string, Header or Form.

Name is the name of the parameter to be used. Make sure these values are URL-Safe (read this post on stackoverflow)!

Required can be used to force a check on the existence of the parameter in the Request, and send a validation error if it is missing.

Target data field is where you map the incoming values to their respective fields in your Data Model, so you can work with the values in flows and pages.

Inherited by nested endpoints allows nested endpoints to inherit this parameter so you only declare and map it once, and it is available to all deeper levels (nested endpoints) and the flows therein.

[URL-Path] Parameters which are dynamic parts of the URL Path can be added using the curly brackets {param-name} into the URL Path. They then get automatically added to the Parameters section so you can map them to the Target data field.

[Query string] Query string parameters can be added by clicking the button “Add query parameter”. You can define the Name as it should be used and please make sure these names are URL-Safe!

[Request Header] Request header fields can be added specifically using the Add Request Header. For a list of available http header fields, check this wiki link. Some Header fields may only contain specific values and the number of fields and length of values is limited.

[Form Fields] Form fields allows you to define specific HTTP Form Fields that can be mapped to WEM Data Model fields. These fields are only available when using verbs that require a Request Body: POST, PATCH, PUT.

Http Endpoint Flowchart

Every HTTP Endpoint that can handle a request (with any other method then “None”) has a flowchart. Once you've created (and configured) the Endpoint, the Flowchart is accessible by double-clicking on the Endpoint in the navigation tree, or by clicking on the Open Flowchart option in the context-menu.

Typically, an HTTP Endpoint Flowchart does not support Interaction Nodes so in fact should be considered to be an Action Flowchart (without user-interaction). It must always end with either an HTTP Response Node, a Navigation Node or a Clear Session node (that also performs a redirect at the end).

The Flowchart Nodes pane has a specific Node to provide the HTTP Response: .

When used in API Integration (server-to-server), it should provide an HTTP Response consisting of an HTTP Response Code and optionally a Response Body.

When used as Web-Hook where a redirect is part of the process provided to the user, you can use the Navigation node to send the user to other parts of the application when this Http Endpoint Node is activated. When the option to use the WEM Runtime Session is active, this navigation will use the existing session.

HTTP Response Properties

Name	the name of the response and is used in the generated open API document
Content type	Provides a value for the Content-Type HTTP Response header. Check [wiki] for common examples.
Status code	Provides a value for the HTTP status code of the response. Check [wiki] for possible status codes - specifically 418.
Response body	Provide value for the data which is sent back to the caller. This should match the defined content type.
Response headers	To allow for the configuration of HTTP response headers. Check [wiki] for standard response values.