Webhooks.md

Webhook Endpoint in IICS Cloud Application Integration

This document describes how to create a Process in IICS Cloud Application Integration that can expose an HTTP endpoint which can accept a POST request to consume a Webhook event and request additional data from the Person API.

Here is IICS Documentation for Cloud Application Integration

Service Connector for OAuth

In the Application Integration module perform the following to create a “Service Connector” for OAuth endpoint:

1. Click “New…”
2. Click “Service Connectors”
3. Click “Service Connector from OpenAPI 3.0”
4. Give the Service Connector a name and provide a source for the OpenAPI specification
   • Download the specification from https://developer.wisc.edu/docs/oauth/1/overview
5. Select the POST operation under “/token” operations for this Service Connector and proceed through the steps
   • There might be warnings with the import which is expected.
6. Once the Service Connector has been created, open the UI for the Service Connector and select the “Actions” tab.
7. Select the Action for POST token and select “Binding” option
8. Select “Basic” as the “Authentication Type”
   • NOTE: you can add your “Client ID” and “Client Secret” here as well to test the connection and the request in the “Test Results” tab.

Process Objects for OAuth

Once the Service Connector has been created, open the UI for the Service Connector and follow these steps to create Process:

1. Select “Process Objects” and click the “+” sign on the right hand side of the list.
2. Process Objects need to map to the responses for each Action that can be performed in a Service Connector.
   • For the OAuth endpoint, create a Process Object that maps the the response here: https://developer.wisc.edu/docs/oauth/1/types/access_token
3. Nested responses can be created by using the “Reference” data type where a property can be referenced to another Process Object.

App Connection for OAuth Service Connector

Once the Service Connector and Process Objects have been created, we need to create an “App Connection” asset to use the Service Connector in a Process.

1. Click “New…”
2. Click “App Connections”
3. Click “App Connection”
4. Fill in the required information
5. For “Type” select the Service Connector created above
6. Add the “Client ID” and “Client Secret” in the Connection Properties section

Service Connector for Person API

In the Application Integration module perform the following to create a “Service Connector” for Person API:

1. Click “New…”
2. Click “Service Connectors”
3. Click “Service Connector from OpenAPI 3.0”
4. Give the Service Connector a name and provide a source for the OpenAPI specification
   • Find OpenAPI specifications here: https://git.doit.wisc.edu/interop/person-api/-/tree/main/apigee#openapi-spec-deployment
   • Or download the specification from https://developer.wisc.edu/docs/person-api/1/overview
5. Select the required Operations for this Service Connector and proceed through the steps
   • There might be warnings with the import which is expected.
6. Once the Service Connector has been created, open the UI for the Service Connector and select the “Actions” tab.
7. For each of the Actions, select the “Input” option
   • Add an “Input Field” of type Text for the OAuth Token (you can name this something that you prefer. I named it “token”) and unselect “Parameter”
8. For each of the Actions, select the “Binding” option
   • Select “Custom” as the Authentication Type
   • Add an “HTTP Header” with name “Authorization” and value “Bearer {$token}” (replace with the name you chose on step 7a above.
9. For each of the Actions, selec the “Output” option
   • Add an “Output Field”, select “Reference” as the type and select the appropriate “Process Object”.
10. NOTE: If you have a valid access_token, you can add it in the “Test with” field in the Input option for the action you want to test.

Process Objects for Person API

Once the Service Connector has been created, open the UI for the Service Connector and follow these steps to create Process:

1. Select “Process Objects” and click the “+” sign on the right hand side of the list.
2. Process Objects need to map to the responses for each Action that can be performed in a Service Connector
   • For Example, for the Person endpoint, create a Process Object that maps the the response here: https://developer.wisc.edu/docs/person-api/1/types/people
3. Nested data structures can be created by using the “Reference” data type where a property can reference another Process Object.

App Connection for Person API Service Connector

Once the Service Connector and Process Objects have been created, we need to create an “App Connection” asset to use the Service Connector in a Process.

1. Click “New…”
2. Click “App Connections”
3. Click “App Connection”
4. Fill in the required information
5. For “Type” select the Service Connector created above
6. Add the “Client ID” and “Client Secret” in the Connection Properties section

Process Objects for the event data structure

We will need to create a Process Object that maps to the event data sent by the Person API Webhook.

1. Click “New…”
2. Click “Process Object”
3. Create Process Objects that maps to the data structured defined in Example webhook event here: https://developer.wisc.edu/person-api/webhooks

Create a Process that can react to a POST request and return a valid HTTP response

After all of the Assets above have been created and tested we can create a “Process” that can utilize them and react to events and perform the desired actions.

Creating a Process

1. Click “New…”
2. Click “Processes” > “Process” > “Create”

Configuring the “Start” step of the process

1. Once created, click “Start” (Green circle) step
2. In the Properties pane for the “Start” step, in the “Start” tab
   • Select “REST/SOAP” as the “Binding”
   • Select “Allow anonymous access”
   • Select “Cloud Server” for “Run On”
3. In the “Input Fields” tab, add the event Process Object created above as the input.
4. Add any Output Fields that might be required for the Process.

Adding a “Service” step for getting an OAuth token

1. In the Design pane, add a “Service” step
2. In the Properties pane for this Service step, in the “Service” tab
   • Select “Connection” as the “Service Type”
   • Select the OAuth App Connection asset created above as the “Connection”
   • Select POST token as the “Action”
3. In the “Input Fields” tab add a field for “grant_type” and set the Value to Content with “client_credentials” as the value.

Adding a “Service” step for getting Person data

1. In the Design pane, add a “Service” step
2. In the Properties pane for this Service step, in the “Service” tab
   • Select “Connection” as the “Service Type”
   • Select the Person API App Connection asset created above as the “Connection”
   • Select the “Action” you need to perform (I used the get_person action as an example)
3. In the “Input Fields” tab, you should see “id” and “token” fields.
   • Map the “id” field to the id value of the person in the event data
   • Map the “token” field to the access_token value of the Response from the POST token step above.

Add additional steps to perform the action your process needs.

Pros and Cons of using IICS CAI as a webhook endpoint

Cons:

1. IICS CAI has limited connector options than IICS CDI
2. Configuring Process Objects can be time consuming
   • This is especially true for Person API as the data structures can be dynamic.
3. Each process needs to be built from scratch
4. IICS CAI does not have the ability to read headers at the start of the process. The Person API Webhook sends a token in the header that consumers can validate to make sure that the event data is coming from the correct source. This is not possible.
   • To facilitate this validation process, changes need to be made to the Person API. Example, send the token in the request body instead.

Pros:

1. It is easy to create an endpoint that can be used as a webhook endpoint.
2. When used in conjunction with an API, it can provide an alternative to ETLs that perform large pulls of data.