HTTP Listener

When to use this listener

The HTTP Listener is used to build user-defined APIs in Integrator.

Creating listener

To create a new HTTP Listener go to Connections, select Listeners tab, click Add Listener button and type in http in the search field. 

Below are the available parameters:

• URL Pattern - the HTTP listener endpoint. The actual endpoint URL starts with {integrator-host}/rest/v1/httplistener and ends with the provided URL. For example, if Integrator Host is https://app.etlworks.com and the URL Pattern is /hl7/patient, the resulting endpoint URL will be https://app.etlworks.com/rest/v1/httplistener/hl7/patient, the HTTP method will be POST, and the payload will be whatever the third-party application sends to this endpoint.

The URL Pattern must be unique across all listeners and all customers. There is a rule: one listener - one flow. Integrator validates against this rule and provides an appropriate error message if someone is trying to create an endpoint that already exists.

Learn more how to define URL pattern.

• Method - HTTP method for the listener. The following methods are available: GET, POST, PUT, DELETE.
• Auth Type - authorization type. The following types are available: JWT - which requires using the Integrator authentication API to obtain an access token, and Basic - which requires a valid username and password.
• Auth Location - authorization data location. If Header is selected, the authorization data, such as access token, username, and password, must be passed as HTTP header parameters. If Query parameter is selected, the authorization data is expected to be passed as query parameters.

• Example of the basic authentication when Auth location is a query parameter: https://app.etlworks.com/rest/v1/httplistener/hl7/patient/?Authorization=Basic%20Base64_encoded_username:password

• Response Preprocessor script (optional) - select which JavaScript script will be executed when a HTTP request with the raw message data arrives to build the HTTP response body and/or pre-process the raw message. Example:

• request.setInput(request.getInput().replace(/ /g, '-')); 
  request.setSuccess(false); value = 'Expected response';
  

In this example, JavaScript does the following:

1. Replaces all white-spaces in the request with the dash - character.

2. Sets the response to "error" (the 500 HTTP code will be returned to the caller).

3. Sets the response body to Expected response.

• Empty GET response code - select which HTTP code should be returned in case of an empty response body (nothing, empty object or empty array). The default is 200 but the REST API standard typically assumes that 404 (not found) should be returned. Keep the default (200) unless the selected method is GET.
• Successful DELETE response code - select which HTTP code should be returned in case of a successful DELETE request. The REST API standard typically assumes that 204 should be returned.
• POST/PUT processing - select whether requests should be processed synchronously, or asynchronously. Only applicable when HTTP method is POST or PUT. GET and DELETE requests are always synchronous.
• POST/PUT Response File Name - the name of the file which contains a response to the request. Only applicable when HTTP method is POST or PUT. If nothing is entered or the file does not exist, the system will return the default response. It is possible to use {tokens}, for example {app.data} as a part of the file name. Read how to configure synchronously executed API endpoint which returns a user-defined response.
• Default Payload - the default payload that should be used in case of POST/PUT request with an empty body.