Webhook Connectors support exposing a public API endpoint.
Webhook Connectors enable data to enter the ArcESB 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.
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.
An XML or JSON template representing the expected structure of incoming data. More details can be found in the Sample Requests Section below.
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.
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.
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
_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-ArcESB-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>