What is a Webhook Contract

The trigger related code involves the design of the inbound webhook request. The webhook request can include headers, query parameters and request body information. To handle a webhook, ensure to set:

• type property to webhook

  The webhook value indicates to the adapter how to handle the headers, query parameters, and the body of the webhook request.

• httpMethod property to POST or as per requirement

The request property references the JSON schema that models the structure of the message. This message appears to the integration developer in the integration mapper.

For a webhook, it might not be necessary to design the headers or query parameters. Depending on the requirement, the adapter developer can expose the webhook body to the integration developer. Business scenarios dictate if the webhook body needs to be transformed into a different form. In this scenario, the request schema and the body schema can be the same as shown in the following example.

Sample code that shows how to design a trigger:

"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"
        }
    }
}

However, if the message exposed to the integration developer is not the same as the structure of the inbound webhook request, the adapter developer can use the execute property to process the webhook and transform into the desired schema that is specified in the request property. The execute can reference a flow. For more information, see Runtime Implementation of Triggers.

For more information on flows, see Flows Properties and Syntax for Dot (.) Notation.

Sample code that shows how to use the execute property to transform the formats during runtime execution:

"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/OrderEventInMapperSchema"
        }
    }
    "execute" : "flow:processOrderWebhookFormatToMapperFormatFlow"
}