What Is a Webhook Trigger

With webhook triggers, external applications automatically send new data to Oracle Integration using webhooks, whenever a specific event occurs in the application. When the new data is received, the integration flow runs and processes the data.

A webhook trigger consists of the following two contracts. The Rapid Adapter Builder supports designing of both these contracts and mapping of one form into the other.

Webhook Contract

A webhook contract is the raw inbound message sent by an external application (likely through an HTTP post) that has headers, query parameters, and body components.

To handle a webhook:

Set the type property to webhook.
Set the httpMethod property to POST or as per your requirement.
In the webhook property, model the headers, query parameters, and the body of the webhook request.
In the request property, reference the JSON schema that models the structure of the message, which appears in the integration mapper.

Note that, for a webhook, it might not be necessary to model the headers or query parameters. Additionally, in most cases, you can present the entire webhook body to the integration developer, and need not transform the raw, inbound webhook request into a different form. Therefore, the request schema and the body schema can generally be the same as shown in the following example.

"OrderProcessedTrigger": {
    "displayName": "Order Processed Event",
    "description": "This event gets triggered when order has been processed.",
    "group": "Orders",
    "type": "webhook",
    "httpMethod": "POST",
    "webhook": {
        "header" : {
            "type": "object",
            "properties": {
                "name" : "x-custom-header",
                "type": "string"
            }
        },
        "body": {
            "schemaType": "application/schema+json",
            "schema": {
                "$ref": "#/schemas/OrderEventSchema"
            }
        }
    }
    "request" : {
        "schemaType": "application/schema+json",
        "schema": {
            "$ref": "#/schemas/OrderEventSchema"
        }
    }
}

Mapper Contract

A mapper contract is the trigger request (modeled in the request property) that appears in the Oracle Integration mapper.

If you want to transform the raw, inbound webhook request into a different form, you can use the execute property to process the webhook and transform the raw request into the desired schema (specified in the request property).

Additionally, both the webhook body and request properties can be driven by flows and derive schemas dynamically.

In the following example, the request property references a flow, which creates a dynamic schema based on a call to the external application's metadata API. This schema is displayed in the Oracle Integration mapper. The execute property also references a flow to transform the webhook message to the final message that is presented to the mapper.

 "OrderProcessedTrigger": {
            "displayName": "Order Processed Event",
            "description": "This event gets triggered when order has been processed.",
            "group": "Orders",
            "type": "webhook",
            "httpMethod": "POST",
            "contentType": "application/cloudevents+json",
            "request": "flow:createRefinedrderEventSchema",
            "webhook": {
                "body": {
                    "schemaType": "application/schema+json",
                    "schema": {
                        "$ref": "#/schemas/OrderEventSchema"
                    }
                }
            }
            "execute" : "flow:processOrderWebhookMsgToRetrieveOrderObjectFlow"
        }

Here is an example of a request flow that demonstrates the creation of the request schema based on a static schema that's enriched with the custom field extension from a metadata API call to an external application.

"createRefinedrderEventSchema": {
    "id": "createRefinedrderEventSchema",
    "version": "0.1",
    "start": "startState",
    "specVersion": "0.8",
    "functions": [
      {
        "name": "getStaticSchema",
        "type": "expression",
        "operation": ".self.schemas.OrderEventSchema"
      },
      {
        "name": "dynamicFlow1",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "dynamicFlow2",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "dynamicFlow3",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "dynamicFlow4",
        "operation": "connectivity::rest",
        "type": "custom"
      },
      {
        "name": "constructResult",
        "type": "expression",
        "operation": ".staticOutput"
      },
      {
        "name": "constructReturnObject",
        "type": "expression",
        "operation": "{\"schemaType\": \"application/schema+json\", \"schema\": .schema}"
      }
    ],
    "states": [
      {
        "name": "startState",
        "type": "operation",
        "actions": [
          {
            "functionRef": "getStaticSchema",
            "actionDataFilter": {
              "toStateData": "${ .staticOutput }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow1",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/Order\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow2",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/Account\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow3",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/PaymentMethod\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
          },
          {
            "functionRef": {
                "refName": "dynamicFlow4",
                "arguments": {
                    "uri": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName+\"/settings/custom-fields/zuora/Contact\"}",
                    "method": "GET"
                }
            },
            "actionDataFilter": {
                "results": "${ .body | .schema.properties | with_entries(select(.value.type != null)) | map_values({type: .type})}",
                "toStateData": "${ .staticOutput.properties }"
            }
            },
          {
            "functionRef": "constructResult",
            "actionDataFilter": {
              "toStateData": "${ .schema }"
            }
          },
          {
            "functionRef": "constructReturnObject",
            "actionDataFilter": {
              "toStateData": "${ .output }"
            }
          }
        ],
        "end": true
      }
    ]
}