Webhooks

Webhook Trigger #

The webhook trigger allows one app to automatically notify Engini through a predefined HTTP callback that an event has occurred.
It allows real-time communication and data exchange between different apps to Engini.

To use this activity, follow these steps:

1. When adding your workflow choose for the trigger “Http” software.
   
   
2. Click on the “Webhook” trigger:
   
   

Follow the next steps to learn how to define this activity:

1. URL
   The URL is automatically created by Engini. It’s not possible to edit it. Click on the icon to the right of the URL to copy it.
   Each webhook URL is unique to the specific workflow you created.
2. Method
   Specifies the type of request that should be sent by the external application.
   The method’s default value is “Post”.
   To define a method, follow the next steps:
   • Click on the empty field.
   • Choose from the tooltip the method you want to use.
     Learn more about the method types in Http Requests guide.
3. Relative URL (Optional)
   specifies the endpoint URL that the trigger will listen to for incoming HTTP requests. To learn more about relative URL click here.
4. Load JSON/XML sample
   To load the sample, there are two options:
   • Using Documentation:
     1. Obtain the JSON/XML payload sample from the documentation of the system that sends the webhook.
     2. Click on the blue sentence to enter a sample of the incoming request payload and Engini will try to parse it and create the structure of the incoming request for you to use in the following activities to extract data from the incoming request.
   • Using the Running Log:
     1. Wait to receive a webhook.
     2. Enter the run history log in Engini.
     3. Expand the webhook output block and scroll to the end of it.
     4. copy the entire “responsebody” value as seen selected in the image below.
        
     5. Switch back to Edit mode and click on the blue sentnce and paste the copied json as seen in the image below.
        

Important

The webhook default response is 200 status code.

Send Webhook Response #

A workflow that is triggered with a webhook will normally send a 200 status code response upon receiving the request. Adding the “Send Webhook Response” activity to a workflow that is triggered with a webhook allows you to customize the response the workflow will return.
You can place this activity in different places inside the workflow, depending on the response you want to send back and when to send it.

Choose the Http software and click on the “Send Webhook Response” action:

To define the webhook response follow the next steps:

1. Status code – Click on the field and choose from the tooltip the status code you want to return.
2. Body Type– Click on the right errow and choose from the tooltip the body type. The activity supports 4 body type:
   • Application/Json
   • File (Application/octet-stream)
   • Text/Plain
   • Text/Xml
3. Body – Click on the empty field to enter the response body you want to return.
4. Add Headers
   Additional metadata about the request, such as the type of data the Engini can accept, the length of the request body, and authentication information.
   1. Click on the “Add Headers” button to add a header.
   2. Click on the key field to enter the key, and on the value field to enter a value.
      Each header consists of a key-value pair, where the key is the name of the parameter, and the value is the data associated with that parameter.
   3. Click on the “add key” button to add more keys.
      

Redirect Example #

To set up a webhook response redirect, configure the Webhook Response module as outlined below:

1. Status Code
   Define a 3xx redirection HTTP status code, such as 303, in the ‘Status Code’ field.
   1. Click on the field and choose from the tooltip the status code you want to return.
   2. ou can select one of these Redirect status codes:
      • 301 – Moved Permanently:
        301 indicates a permanent URL redirection. The requested resource has been permanently moved to a new URL. Subsequent requests should use the new URL
      • 302 – Found/Temporary Redirect:
        302 signifies a temporary redirection. It tells the client to temporarily visit a different URL. Future requests should still use the original URL.
      • 303 – See Other:
        303 advises the client to visit another URL. It is typically used in response to a POST request, redirecting the user to another page to retrieve the response.
      • 307 – Temporary Redirect:
        307 indicates a temporary redirection similar to 302 but preserves the method (GET, POST, etc.) used in the original request for future requests.
      • 308 – Permanent Redirect:
        308 is similar to 301 but preserves the method (GET, POST, etc.) used in the original request for future requests. It signifies a permanent URL redirection.
2. Headers
   Add the following custom header details:
   • Key: Location
   • Value: The URL you intend to redirect to. For example, “https://www.EnginiExample.com”.

This configuration directs the response to a specified URL upon trigger.

Relative URL #

In the context of webhooks, a relative URL is a way to specify a resource’s link relative to the webhook’s endpoint. Instead of providing the full and absolute URL, a relative URL allows you to insert dynamic parameters or variables into the link. When the webhook is triggered, you can utilize the values received in the properties for further processing within your workflow.

Using a Relative URL Example, let’s consider the following scenario: Suppose you have the following webhook endpoint:
URL: https://workflowapi.engini.io/webhook/v2/123engini456example/{itemId}

When you want to utilize this link and replace the value of “itemId,” you specify the desired value in the appropriate place within the URL. For instance, if you want to trigger the workflow with an “itemId” of 123, use the following URL:
https://workflowapi.engini.io/webhook/v2/123engini456example/123

Customization:
The “itemId” is just an example and can be named and used as per your preferences. You can also include multiple properties separated by commas in the URL to pass and process various data as needed. For example, you can format your URL like this:
https://workflowapi.engini.io/webhook/v2/{property1}/{property2}/{property3}