Webhook Triggers

ArcESB supports flexible webhook triggers to integrate with systems that send relevant data via web request. The Webhook Connector exposes a public endpoint guarded behind specific groups of authorized users.

• Webhook Endpoints
• Authorization
• Web Request Content
  • Webhook as a Trigger
  • Handling Incoming Data
    • Integrating with a Database

Each Webhook Connector in the Arc Flow exposes a separate endpoint based on the Connector ID (the connector’s name). A Webhook Connector’s endpoint follows this syntactical convention:

http[s]://<host>:<port>/connector/[workspace]/<connector_id>/webhook.rsb

Note: Webhook Connectors in the default Workspace do not include the ‘[workspace]’ element of the endpoint URL.

Data POSTed to this endpoint will trigger the Webhook Connector to generate an output file based on the contents of the web request. If the Webhook Connector is part of a configured Flow, the output file will be passed along the Flow and cause the succeeding connectors to process the data like any other file.

POSTs to the Webhook URL may be used as simple triggers to invoke other elements of an Arc Flow (i.e. the web request itself might not contain any relevant data), or they can be used as an entry point for specific data that should be processed by the application.

Each Webhook Connector maintains its own list of authorized users in the Users tab of the connector configuration panel. Note: this list of users is separate from the users who are authorized to access the Admin API or any other endpoint exposed in the application.

Each user is granted an Authtoken, which can be used as a password for basic/digest authentication, or can be set as the value for the following header in the web request:

x-arcesb-authtoken: myAuthTokenValue

The Webhook Connector does not impose any strict content restrictions on web requests received by the application. This helps ensure that Arc can integrate with any system that triggers execution via web requests.

Requests received via the Webhook Connector typically fall into two categories:

• The webhook is invoked simply to trigger the execution of an independent Flow
• The webhook receives data that should be manipulated and integrated into the Flow

Any time a Webhook Connector receives a web request, it writes a corresponding output file and pushes this file into the Arc Flow. Regardless of the specific content within the incoming request, all incoming messages serve as a trigger for the Flow to which the Webhook Connector is attached.

However, the Webhook Connector does validate the content-type of the incoming web request against the Sample Request settings in the Settings tab (XML or JSON). Any web request triggers should use the appropriate content-type header (application/xml or application/json).

Aside from the content-type, the Webhook Connector does not enforce validation of the content of incoming web requests. As such, the remainder of the Sample Request section can be safely ignored if the incoming data does not need to be manipulated or integrated into another part of the Flow.

The Sample Request section of the Webhook Connector configuration can be used to model the structure of the incoming web request data. As mentioned in the previous section, the Webhook Connector does not perform strict validation against this sample request, however this sample request structure helps easily manipulate the data once it has been received into the Arc Flow.

The Sample Request should be used in conjunction with the XML Map Connector to integrate the web request data into the Flow. The logic is as follows:

• The Sample Request models a JSON or XML structure that represents data incoming via the webhook
• This data needs to be transformed into some other structure to integrate with the rest of the Arc Flow
• The XML Map Connector performs this structure-mapping via a powerful visual designer
• The XML Map Connector can read the Sample Request structure and use it as a starting point in the mapping (i.e. the Source File)
• Any desired XML file can be uploaded as the target XML structure (i.e. the Destination File)
• Then the XML Map Connector maps the format of the webhook request into the desired format necessary for the Arc Flow

In other words, Sample Request is useful because it allows Arc to know how to map incoming data into whatever format is most useful for the Flow.

Note that when the Sample Request format is set to JSON, the Webhook Connector will automatically convert this to XML when generating an internal model of the request. Thus, no extra steps are required to use the Webhook Connector with the XML Map Connector when sending JSON requests.

For example, imagine that a backend system like HubSpot sends real-time notifications when records are added or updated. These notifications need to be received via webhook, and the data in this notification needs to be pushed into a MySQL database. The INSERT/UPDATE (UPSERT) into the database is modeled as XML in Arc, so the task is to transform the structure of the incoming request into the XML structure for the UPSERT.

The Arc Flow to accomplish this would be a Webhook -> XML Map -> MySQL Flow:

The UPSERT to the MySQL database is modeled as XML by creating an Input Mapping (in the MySQL Connector) for the appropriate database table. The Webhook structure is modeled as XML by specifying an example request in the Sample Request field of the Webhook Connector. The XML Map Connector reads both of these models and exposes them as possible Source File and Destination File templates.

Then, the visual designer in the XML Map Connector will populate with both structures, allowing for dragging-and-dropping elements from the Source onto the Destination to establish the mapping relationship.

Once complete, data received via webhook is automatically mapped into an UPSERT and the MySQL database remains synchronized with the backend system sending the notification.