# SENDHTTPPOST Workflow Application
## Overview
The **SENDHTTPPOST** workflow application lets you create outgoing webhooks to external systems. Webhooks allow an API to exchange information with other applications through HTTP POST requests, and can be used to build integrations with extendable applications such as Slack, GitHub, and Dropbox. For example, they can be used for notifications when an expected event (as previously configured by the user) has occurred. Since they allow real-time communication, webhooks are efficient and performant.
The SENDHTTPPOST workflow application sends outgoing webhooks to external applications using JSON or URLENCODED payloads. SENDHTTPPOST will then receive and process the response from the external API. For more information, see the [Using webhooks with WorkflowGen](https://discuss.workflowgen.com/t/using-webhooks-with-workflowgen/675) topic on the [WorkflowGen Forum & Knowledge Base](https://discuss.workflowgen.com/).
For an example of how you can use SENDHTTPPOST to send messages to Slack channels from WorkflowGen, see [Workflow Application: Using SENDHTTPPOST to send messages to Slack](https://discuss.workflowgen.com/t/workflow-application-using-sendhttppost-to-send-messages-to-slack/673). As well, samples of APIs that use SENDHTTPPOST are available in the [SENDHTTPPOST Workflow Application](https://github.com/advantys/workflowgen-templates/tree/master/integration/webhooks/sendhttppost) repository on GitHub.
## How it works
* The default payload content type (`APP_CONTENT_TYPE`) is JSON; URLENCODED is also supported.
* Since the application parameters are case-sensitive, parameters must use the API’s accepted notation.
* The SENDHTTPPOST application requires the `APP_URL` parameter, which corresponds to the external API URL.
* The `TOKEN` parameter is available for authentication for external APIs where the token is not included in the URL. In these cases, the token will be sent in the payload using the `TOKEN` parameter.
* The response can contain an optional payload mapped to user-defined OUT parameters.
* In case of error when then `APP_RESPONSE_STATUS OUT` parameter is not defined, an exception will be triggered; `2xx` HTTP response status codes are successful responses.
* Besides the optional parameters listed below, you can also add additional custom IN and OUT parameters (specific to the external API) to send and receive custom user-defined data to and from the external API. For example, in a Slack integration, you can add a parameter to include an emoji in a Slack message, and map this to Slack’s `"icon_emoji"` parameter (this is the Slack API’s accepted notation for this particular parameter).
* The default timeout (`APP_TIMEOUT`) is 3000 milliseconds; the maximum timeout is 60,000 milliseconds.
* The HTTP request headers can be defined with the `APP_HEADER_xxx` parameters, where `xxx` is the header field name.
* The default maximum response length is 4194304 characters (4 MB); this default value can be modified by setting the `SendHttpPostMaxResponseLength` parameter value in the `web.config` file.
* Application logs are available; these can be specified by setting the `SendHttpPostLogLevel` parameter value in the `web.config` file to `0` to disable logging, `2` for simple logs, or `3` for debug logs.
### Examples of JSON payloads
A payload created by SENDHTTPPOST to send a message to a Slack channel would look something like this:
```
{
"channel": "#marketing-channel",
"text": "This is a test",
"username": "eric_knox"
}
```
A payload created by SENDHTTPPOST to send nested JSON to be converted into objects by an external API would look something like this:
```
{
"Person": {
"Address": {
"Street": "Test",
"Zipcode": "XXX XXX"
},
"Age": 30,
"Name": "John"
}
}
```
## Parameters
### Required parameter
| Parameter | Type | Direction | Description |
| --------- | ---- | --------- | ---------------- |
| `APP_URL` | Text | IN | External API URL |
### Optional parameters
| Parameter | Type | Direction | Description |
| ------------------------------ | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TOKEN` | Text | IN | API authorization token (use this parameter to specify a token for external APIs that don’t include the token in the URL) |
| `APP_TIMEOUT` | Numeric | IN | Maximum time interval between the request sending and the response reception (default: 3000 milliseconds; maximum 60,000 milliseconds) |
| `APP_CONTENT_TYPE` | Text | IN | Request content type supported by the external API (SENDHTTPPOST supports JSON and URLENCODED; the default is JSON) |
| `APP_RESPONSE_CONTENT` | Text | OUT | Returned optional payload or error message |
| `APP_RESPONSE_STATUS` | Text/Numeric | OUT | Returned HTTP request status code |
| `APP_HEADER_xxx` | Text | IN | External API header parameters where `xxx` is the header field name |
| `APP_REQUEST_CONTENT_IS_ARRAY` | Text | IN | When set to Y, the application will convert the JSON request payload into an array; the default is N
Only supported when building JSON request payload with IN parameters.
|
## Examples
### Header parameters
| Parameter | Type | Direction | Value |
| -------------------------- | ---- | --------- | --------------------- |
| `APP_HEADER_Authorization` | Text | IN | `Bearer AbCdEf123456` |
| `APP_HEADER_location` | Text | IN | `canadaeast` |
The parameters defined above will generate two headers in the request payload:
```
Authorization: Bearer AbCdEf123456
location: canadaeast
```
### Convert JSON request payload into an array
When setting the parameter `APP_REQUEST_CONTENT_IS_ARRAY` to `Y`, it will convert the JSON into an array:
```
[{
"person": {
"address": {
"street": "160 Guy Street",
"zipcode": "J4G 1U4"
},
"age": 30,
"name": "John"
}
}]
```