Application

Webhook Trigger

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

Webhook Trigger

Node Properties

The Webhook Trigger takes a single configuration property: the webhook for which the workflow should trigger when an HTTP request or WebSocket event 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 the Webhook Trigger differs based on the type of webhook (HTTP vs WebSocket).

HTTP Webhook Payload

The payload for an HTTP Webhook Trigger includes 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, consider the following request submitted through curl:

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

This is …

  • A POST request …
  • Submitted to a webhook set to wait for a reply and parse multipart file uploads …
  • With an additional path of “/transition/up” …
  • And a query parameter of “location” with a value of “52” …
  • And three values submitted in the body of the request - one of which is a file upload.

This results in the following Webhook Trigger payload:

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "body": {
      "age": "42",
      "name": "Jane",
      "exampleFile": {
        "filename": "myUpload.txt",
        "headers": {
          "content-disposition": "form-data; name=\"exampleFile\"; filename=\"myUpload.txt\"",
          "content-type": "text/plain"
        }
      }
    },
    "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"
}

WebSocket Webhook Payload

A WebSocket webhook will trigger your workflow when …

  1. A client makes a WebSocket connection.
  2. A connected client sends a WebSocket message.
  3. A client connection is closed.

WebSocket connections are persistent and it is common to receive multiple WebSocket messages between a client connection and disconnection.

The payload for a WebSocket Webhook Trigger includes information about the request in the data object:

  • type: Indicates the action that triggered this webhook (connect, message, or disconnect).
  • message: Contains additional information based on the type of message received.
    • For connect types, this will be an empty object.
    • For message types, this object contains two fields: data and length. The data field contains the raw WebSocket data sent by the client. The length field contains the length, in bytes, of the raw WebSocket data.
    • For disconnect types, this object contains two fields: reason and statusCode. If a client closes the connection, these values are provided by the client. If the connection is closed by the platform, the reason field will blank and the statusCode will be one of the platform’s disconnect codes.
  • 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.) For WebSockets, even though headers are only received when the underlying connection is initially established, the platform stores and provides the original header fields on all subsequent messages sent by the client, including the disconnect message.
  • method: The HTTP method by which the request was sent. The method is provided in lowercase letters. For WebSockets, this is always set to get.
  • 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: A unique identifier that represents a specific WebSocket client. This value is provided for all message types and does not change for the duration of the client connection. This value is used to send WebSocket messages from the platform to the client using the Webhook Reply Node.

The example payload below represents a WebSocket client sending a message.

{
  "applicationId": "555555555555eeeeeeeeeeee",
  "applicationName": "My Great Application",
  "data": {
    "message": {
      "data": "Hello World",
      "length": 11
    },
    "headers": {
      "connection": "upgrade",
      "sec-websocket-extensions": "permessage-deflate; client_max_window_bits",
      "sec-websocket-key": "<websocket handshake value>",
      "sec-websocket-version": "13",
      "upgrade": "websocket",
      "x-forwarded-for": "<source IP address>",
      "x-forwarded-proto": "https",
      "x-real-ip": "<source IP address>",
      "x-ssl-proto": "TLSv1.3"
    },
    "method": "get",
    "path": "/",
    "query": {},
    "replyId": "<ID of webhook>.<Unique request ID>",
    "type": "message"
  },
  "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"
}

WebSocket Disconnect Codes

If the platform disconnects a WebSocket client, the statusCode will be set to one of the following values:

  • 1006: Indicates an abnormal closure. This is usually due to the client crashing or the client’s underlying connection ending without the platform receiving a proper WebSocket disconnect message.
  • 1008: The WebSocket connection has exceeded the platform’s rate limits.
  • 1009: A client attempted to send a WebSocket message that is too large. The maximum WebSocket message size is 256KB.
  • 1012: The platform has disconnected the client to perform system maintenance.

If you receive a statusCode not listed above, it is because the client closed the connection and provided its own code to indicate why.

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.

To prevent cross-site scripting attacks, the Cookie header is stripped out of incoming webhook requests. This is because the triggers.wnology.io 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

HTTP 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.

For WebSocket webhooks, the Webhook Reply Node is used to send a WebSocket message from the platform to the client. With this type of webhook, the Webhook Reply Node can be used any number of times to send any number of messages from the platform to the client.

Was this page helpful?

Still looking for help? You can also search the WEGnology Forums or submit your question there.