#Webhook

#Introduction

The Webhook trigger provides a URL that can be called by third-party systems via HTTP requests. When a third-party event occurs, it sends an HTTP request to this URL to trigger the workflow execution. It is suitable for notifications initiated by external systems, such as payment callbacks, messages, etc.

#Creating a Workflow

When creating a workflow, select the type "Webhook event":

#Trigger Configuration

#Webhook URL

The URL for the Webhook trigger is automatically generated by the system and bound to this workflow. You can click the button on the right to copy it and paste it into the third-party system.

Only the POST HTTP method is supported; other methods will return a 405 error.

#Security

HTTP Basic Authentication is currently supported. You can enable this option and set a username and password. Include the username and password in the Webhook URL in the third-party system to implement security authentication for the Webhook (for details on the standard, see: MDN: HTTP authentication).

When a username and password are set, the system will verify if the username and password in the request match. If they are not provided or do not match, a 401 error will be returned.

#Parse Request Data

When a third party calls the Webhook, the data carried in the request needs to be parsed before it can be used in the workflow. After parsing, it becomes a trigger variable that can be referenced in subsequent nodes.

The parsing of the HTTP request is divided into three parts:

1. Request Headers

   Request headers are usually simple key-value pairs of string type. The header fields you need to use can be configured directly, such as Date, X-Request-Id, etc.

2. Request Parameters

   Request parameters are the query parameters in the URL, such as the query parameter in http://localhost:13000/api/webhook:trigger/1hfmkioou0d?query=1. You can paste a full sample URL or just the query parameter part and click the parse button to automatically parse the key-value pairs.

Automatic parsing will convert the parameter part of the URL into a JSON structure and generate paths like `query[0]`, `query[0].a` based on the parameter hierarchy. The path name can be manually modified if it doesn't meet your needs, but usually, no modification is required. The alias is the display name of the variable when used, which is optional. The parsing will also generate a full list of parameters from the sample; you can delete any parameters you don't need.

3. Request Body

The request body is the Body part of the HTTP request. Currently, only request bodies with a `Content-Type` of `application/json` are supported. You can directly configure the paths to be parsed, or you can input a JSON sample and click the parse button for automatic parsing.

Automatic parsing will convert the key-value pairs in the JSON structure into paths. For example, `{"a": 1, "b": {"c": 2}}` will generate paths like `a`, `b`, and `b.c`. The alias is the display name of the variable when used, which is optional. The parsing will also generate a full list of parameters from the sample; you can delete any parameters you don't need.

#Response Settings

The configuration of the Webhook response differs between synchronous and asynchronous workflows. For asynchronous workflows, the response is configured directly in the trigger. Upon receiving a Webhook request, it immediately returns the configured response to the third-party system and then executes the workflow. For synchronous workflows, you need to add a response node within the flow to handle it according to business requirements (for details, see: Response Node).

Typically, the response for an asynchronously triggered Webhook event has a status code of 200 and a response body of ok. You can also customize the response status code, headers, and body as needed.

#Response Node

Reference: Response Node

#Example

In a Webhook workflow, you can return different responses based on different business conditions, as shown in the figure below:

Use a conditional branch node to determine if a certain business status is met. If it is, return a success response; otherwise, return a failure response.