Webhook Trigger Activity

A Webhook is an HTTP callback that can be triggered by an event from a third-party application. This event initiates an HTTP request to the configured URI on the Webhook workflow, subsequently triggering the workflow with any data included in the request.

To create a Webhook workflow, select the Webhook option within the Create Workflow modal, as shown below.

The URI for the Webhook will be automatically generated and can be found on the properties page of the Webhook activity. You can copy the URI to your clipboard by clicking on the copy button.

Using the Webhook

The Webhook activity supports HTTP requests via GET or POST methods. The activity provides the following information from the request, which can be utilized within the workflow:

• Method: The HTTP method used for the request, which could be GET or POST.
• Body: The body of the HTTP request, adhering to HTTP standards. Note that a GET request does not contain a body.
• Query: The values specified in the query string of the request, converted into an object for individual access. For example, query string parameters like "?param1=value1&param2=value2" can be accessed through JSON Paths like $.activity.webhook.query.param1 and $.activity.webhook.query.param2.
• Header: The values of each header element, similarly converted into an object for individual access. For instance, accessing the authorization element via a JSON Path would look like $.activity.webhook.header.authorization.

The webhook can accept various forms of data within the body, but only JSON data is automatically converted into an object. Any request containing JSON data must include the header:

Content-Type: application/json

For example, the following JSON data:

{
  "message": "My first webhook workflow",
  "user": "John Smith"
}

Would be converted into an object and can be accessed via a JSON Path like $.activity.webhook.body.message.

Any request lacking this header or containing a different content type will be treated as plain text.

Waiting for a Reply

By default, when you call a Webhook workflow, you receive an immediate 200 response with a text value of "OK," and the workflow continues to execute in the background. If you want the request to wait until the workflow has completed or you'd like the workflow to return a value, you can modify the response settings.

1. Open your workflow.
2. Select the Webhook trigger.
3. Check Respond after execution completes on the settings page.
   
   
   
4. Then click Save.

By default, the client request will wait for 120 seconds for the workflow to complete before timing out. You can adjust this setting as needed, with a minimum value of 10 seconds.

To configure your workflow to send a response, you need to add a Webhook Response activity. You can place this activity at any point in your workflow, and if your workflow has multiple branches, you can add multiple response activities, though only one of them can return a value. If multiple response activities are executed, subsequent activities will fail with a warning message stating that an HTTP response has already been sent.

To set up a Webhook Response, follow these steps:

1. Add a new Webhook Response activity.
   
   
   
2. The response activity allows you to modify the HTTP status code, body, and headers of the response.
   
   
   By default, the status code is set to 200, but you can change it to any valid HTTP status code. The body can be in JSON, XML, or any data structure you require, provided you include the corresponding response headers in the headers section.
   
   In this example, we will return some basic JSON.
   
   
   
3. Once you have configured the activity, click Save.

The Delay Activity

When a Webhook workflow is configured to send a response, the Delay Activity will be ignored, and you will receive a warning message if you have included one in your workflow.