Webhook Trigger Node

The Webhook Trigger fires a workflow whenever the selected webhook receives an HTTP request.

Node Properties

The Webhook Trigger takes a single configuration property: the webhook for which the workflow should trigger when a request is received. After choosing a webhook, the webhook’s URL will appear below the selector.

In the above example, the workflow will be triggered whenever the “External Command Hook” webhook receives a request.

Payload

The payload for a Webhook Trigger includes all of the information about the triggering request in the data object:

• body: The value sent in the request body. The shape of this value depends on what is included in the request. When using an HTTP method that does not support a body (such as a GET request), this value will be null. (Note: Data submitted through a form – that is, with a Content-Type of “multipart/form-data” or “application/x-www-form-urlencoded” – is automatically parsed into JSON.)
• headers: An object whose keys represent the headers sent in the request, the value of each being a string representing that header’s value. Keys are all lowercased. (Note: Some request headers are stripped for security purposes.)
• method: The HTTP method by which the request was sent. The method is provided in lowercase letters.
• path: A string containing any characters added to the end of the webhook URL. The value always begins with a slash (/). If no characters are provided, this value will be just /.
• query: An object whose keys represent query parameters included in the request. If no query parameters are included, this will be an empty object.
• replyId: If the webhook is configured to wait for a reply, this value will be present. It is a unique identifier for the specific request and can be referenced in a Webhook Reply Node.

For example, given a POST request made to a webhook configured to wait for a reply, with data submitted as form data,the following request made using

For example, consider the following request submitted through curl:

curl --request POST 'https://triggers.losant.com/webhooks/bZsimcQuetyXlxRKwl5cI5gLy604cbukgJ3lLkkJ/transition/up?location=52' \
--form 'name="Jane"' \
--form 'age="42"'

This is …

• A POST request …
• Submitted to a webhook (configured to wait for a reply) …
• With an additional path of “/transition/up” …
• And a query parameter of “location” with a value of “52” …
• And two values submitted in the body of the request.

This results in the following Webhook Trigger payload:

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "body": {
      "age": "42",
      "name": "Jane"
    },
    "headers": {
      "accept": "*/*",
      "content-length": "237",
      "content-type": "multipart/form-data",
      "user-agent": "curl/7.77.0",
      "x-forwarded-for": "<source IP address>",
      "x-forwarded-proto": "https",
      "x-real-ip": "<source IP address>"
    },
    "method": "post",
    "path": "/transition/up",
    "query": {
      "location": "52"
    },
    "replyId": "<ID of webhook>.<Unique request ID>"
  },
  "flowId": "333333333333cccccccccccc",
  "flowName": "My Great Workflow",
  "flowVersion": "myFlowVersion",
  "globals": {
    "aJsonGlobal": {
      "key": "value"
    },
    "aNumberGlobal": 42,
    "aStringGlobal": "My value"
  },
  "relayId": "000000000000000000000000",
  "relayType": "public",
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "triggerId": "<ID of webhook>",
  "triggerType": "webhook"
}

Notes

There are multiple considerations to take into account when working with the Webhook Trigger.

Maximum Payload Size

As with all workflow triggers, the maximum size of the initial payload is 256KB, which includes all the headers, parameters, and body from a webhook request. Therefore, care should be taken (especially with POST bodies) to stay under this limit.

Stripped Cookie Headers

To prevent cross-site scripting attacks, the Cookie header is stripped out of incoming webhook requests. This is because the triggers.losant.com domain is shared across all webhooks, and so cookies could unintentionally leak sensitive information across applications. If you need to use cookies, Experience Endpoints and the Endpoint Trigger will allow you to do so in a more secure manner, since domains for Experience Endpoints are application-specific.

Replying to Requests

As mentioned, webhooks can be configured to wait for a reply from the workflow engine. If this option is selected, your workflow execution must include a Webhook Reply Node to issue a reply to the request; otherwise, your webhook users will see their requests time out.

Bear in mind also that the first Webhook Reply Node to be encountered for a given request - in the same workflow or across multiple workflows - will issue the reply to the request.

Related Nodes

• Endpoint Trigger
• Webhook Reply Node