// This module is included in the following assemblies:
// as_triggering-integrations-with-http-requests.adoc

[id='start-with-webhook-connection_{context}']
= Creating an integration that an HTTP request can trigger

To trigger execution of an integration with an HTTP `GET` or `POST` request,
add a Webhook connection as the integration's start connection. 

.Procedure

. In the {prodname} panel on the left, click *Integrations*.
. Click *Create Integration*.
. On the *Choose a connection* page, click the Webhook connection.
. On the *Choose an action* page, select the *Incoming Webhook* action. 
+
In the *Webhook Configuration* page, {prodname} displays the webhook
token that {prodname} generates for this integration. 
+
When you construct the HTTP request, this token is the last part of the URL. 
After you publish this integration and it is running, {prodname} displays
the {prodname} external URL, which has this token at the end. 
+
The *Webhook Configuration* page also includes *Default Response* and *Error Handling* sections. The webhook step sends a response to the HTTP client that invoked it. The response contains one of the return codes and, by default, the error message in the body of the returned message.

. Under *Default Response*, in the *Return Code* field, accept the default response that {prodname} displays, or use the drop-down list to select the default response that you want. The flow sends this response when execution of the operation flow does not return any of the configured error responses. Typically, the default response return code indicates a successful operation. 

. Under *Error Handling*, indicate whether you want to include the error message in the body of the returned message. 
+
During development, you typically want to return the error message. In production, however, you might want to hide the error message if it contains sensitive or proprietary information. The error message is a JSON-formatted string that contains `responseCode`, `category`, `message`, and `error` elements, for example: 
+
[source,json]
----
   {
      responseCode: 404,
      category:  "ENTITY_NOT_FOUND_ERROR",
      message: "SQL SELECT did not SELECT any records"
      error: SYNDESIS_CONNECTION_ERROR
    }
----
+
Note that during development, the most reliable way to know that an error happened is to check the `HTTP_RESPONSE STATUS` header in the response to the caller. You can also check the integration pod’s log for `INFO` messages. The integration’s *Activity* log shows a successful exchange and errors are not always visible in the *Activity* log.

. For each error that the webhook step might return, accept the default return code or use the drop-down list to select another HTTP status return code. 

. Click *Next*. 
. In the *Specify Output Data Type* page:
.. Click in the *Select Type* field, and select *JSON schema*.
.. In the *Definition* field, paste the JSON schema that defines the data 
types of the parameters in the HTTP request. See 
link:{LinkSyndesisIntegrationGuide}#about-json-schema-for-http-requests_webhook[About the JSON schema for specifying request parameters]. 
.. In the *Data Type Name* field, specify a name for this data type. 
Although this is optional, if you specify a name, it appears in the 
data mapper *Sources* list, which can make it easier to correctly map fields. 
.. Optionally, in the *Data Type Description* field, provide some information 
that helps you distinguish this data type.
.. Click *Next*. 
. Add the finish connection to the integration. 
. Add any other needed connections.
. Add any other needed steps.
. Immediately after the start connection, add a data mapper step. 
. Click *Publish*, give the integration a name and, optionally, a description, custom environment variables, and one or more labels. 
. Click *Save and publish*. 
