Search

Webhook Connector

Version 22.0.8473

Webhook Connector

Webhook Connectors support exposing a public API endpoint.

Overview

Webhook Connectors enable data to enter the CData Arc flow via HTTP POSTs and PUTs. Each Webhook Connector exposes an endpoint in the application where external clients can send XML and JSON payloads. These payloads are written to an output file and passed along to connected connectors in the flow.

A Sample Request can be specified in the Webhook Connector to simplify the process of transforming data that is POSTed to the endpoint. When an XML sample is specified, and the Webhook Connector is connected to an XML Map Connector in the flow, the XML Map Connector can automatically detect the expected structure of XML files posted to the endpoint. The visual designer of the XML Map Connector can then be used to map this structure into any arbitrary target XML structure.

Connector Configuration

Settings Tab

Connector Details

Settings related to the core operation of the connector.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • Webhook Endpoint The generated URL (based on connector name) where the endpoint is exposed.
  • HTTP Method Whether to allow data to be uploaded via POST calls, PUT calls, or both.

Miscellaneous

Settings for specific use cases.

  • Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Sample Request

An XML or JSON template representing the expected structure of incoming data. More details can be found in the Sample Requests Section below.

Server Tab

Trusted IP Addresses

This section defines the IP addresses that are allowed to make connections. The following functions are available:

  • Add Opens a modal to enter a new IP address range.
  • Edit Opens a modal to modify the selected IP address range.
  • Delete Deletes the selected IP address range from the list.

The following restrictions apply to this feature:

  • localhost cannot be modified or removed from the list.
  • Any IP addresses outside of the defined ranges will be rejected.
  • Ranges are supported. For example, the entry 100.10.100.1-15 indicates that IP addresses between 100.10.100.1 and 100.10.100.15 are allowed.
  • CIDR notation is supported. For example, the entry 100.10.100.0/24 indicates that IP addresses between 100.10.100.0 and 100.10.100.255 are allowed.
  • Wildcard patterns are supported. For example, the entry 100.10.100.* indicates that IP addresses beginning with 100.10.100 are allowed.

Authentication

Users access Webhook resources by providing auth tokens with requests. You can manage users and auth tokens on the Users tab of the Webhook Connector settings pane.

Before users can call the Webhook endpoint, you also need to set trusted IP addresses for connections. These settings are available on the Server tab of the Webhook settings pane. By default, all IP addresses are restricted.

Using Auth Tokens in Basic Authentication

Enter the user’s auth token as the password when using Basic Authentication.

Using Auth tokens in the HTTP Header

Add the HTTP header x-cdata-authtoken with the desired auth token as part of the HTTP request.

Using Auth Tokens as Query String Parameters

To allow the connector to pass the auth token in query string parameters, open the Server tab of the Webhook Connector settings pane and select Allow authtoken in URL in the Advanced Settings section.

After enabling this feature, you can specify the auth token as the value of the @authtoken parameter, which can be supplied as part of the HTTP form-post data or a query parameter.

Receiving Data

When data is uploaded to the Webhook Endpoint, the body of the web request is written as an output file and passed along to the next connected connector in the flow. This allows for a flexible method of invoking an Arc workflow via an external API call.

Data uploaded to the endpoint is not validated within the Webhook Connector, and should be validated later in the flow if necessary.

Sample Requests

The Sample Request field allows for specifying the XML or JSON structure expected for API calls to the webhook endpoint.

The primary benefit of specifying a sample request is when connecting the Webhook Connector to an XML Map Connector in the flow. XML Map Connectors should be used when the API data needs to be converted into some other format, like an EDI document or a database insert.

The XML Map Connector can detect the XML structure of the sample request and use this as the Source File for the XML Map designer. Then, the XML structure representing the target format should be uploaded as the Destination File for the XML Map Connector, at which point the visual designer can be used to convert the source structure into the destination.

Custom Responses

Ordinarily, the Webhook Connector will accept the post data with a token response that the request was accepted, but the response may be customized through the use of the Response event, where the _request, _httpheaders, _response, and _message special items are available. When specified, the connector expects the custom response to be provided through the _response item. As an example, to surface a header on the incoming request as a header on the message that is passed down the flow, the ArcScript in the Response event might look something like this:

<arc:set attr="_message.header:MySpecialHeader" value="[_httpheaders.MyWebhookHeader]" />
<arc:set attr="_response.header:Content-Type" value="application/xml" />
<arc:set attr="_response.write" value="<Status>Successfully processed message with MySpecialHeader=[_message.header:MySpecialHeader]</Status>" />

With the above ArcScript in the Response event, a client may send a request similar to the following:

POST https://localhost/connector/Webhook1/webhook.rsb HTTP/1.1
content-type: application/xml
X-Arc-Authtoken: 1s7U4w0a2P3l8v9W3l0q
MyWebhookHeader: Hello World!

<Items>
  <Webhook>Hello World!</Webhook>
</Items>

and receive the following response:

HTTP/1.1 200 OK
Connection: close
Date: Tue, 31 Aug 2021 19:16:13 GMT
X-Frame-Options: SAMEORIGIN
Content-Type: application/xml
Content-Length: 81
Server: Jetty(9.4.z-SNAPSHOT)

<Status>Successfully processed message with MySpecialHeader=Hello World!</Status>