Skip to content

Martini Workflows Webhook Trigger Node

Overview

A webhook is an HTTP endpoint that enables external applications or services to send HTTP requests into Martini workflows. Using the Webhook Trigger Node is a quick and easy way for enterprise developers to expose business processes and integrate systems via webhooks.

How It Works

When Martini receives an HTTP request that matches the configured endpoint (method and URL path), it immediately triggers the workflow and passes any values from the request (such as path parameters, queries, headers, or body) to your workflow for processing.

What You'll Learn

  • How to add and configure a Webhook Trigger Node in your workflow
  • How to map incoming request data (path parameters and queries) to workflow input properties
  • How to access and use the Webhook trigger's input properties like $request and $response in your workflow logic
  • How to map workflow output to HTTP response for controlling webhook responses
  • How to test your Webhook Trigger Node using Martini Designer
  • Key differences between webhooks and full blown REST API operations

When To Use This

Use this when you need to:

  • Integrate with third-party services (e.g., payment gateways, messaging platforms, cloud services)
  • Automate business processes triggered by incoming data (e.g., customer sign-ups, order placements)
  • Synchronize data between systems
  • Send custom notifications to users or teams based on external triggers
  • Expose a workflow as a simple single HTTP endpoint without any authentication requirements

Prerequisites

Getting Started

Add a Webhook Trigger Node To Your Workflow

  1. Expand your Martini Package in the Navigator and select your workflow.
  2. Click the Add Node button in the Workflow Designer toolbar on the top left.
  3. Select Webhook Trigger from the node types.
  4. Drag the Webhook Trigger Node to your desired position in the workflow.
  5. Connect it to other nodes using workflow edges.

Configuring Your Webhook Trigger Node

  1. Click the expand icon on your Webhook Trigger Node to open the Webhook Trigger panel.
  2. Select the HTTP method(s) to trigger the webhook (e.g., GET, POST) by checking the appropriate boxes.
  3. Enter the URL path for your webhook endpoint, starting with a leading / (e.g., /mypath).

Expected result:
A Webhook Trigger Node appears in your workflow, ready to receive HTTP requests.

After setup, you can:

Using Workflow Input Properties with your Webhook Trigger Node

Your webhook event/request can include:

  1. Path Parameters
  2. Query Parameters
  3. Headers

Any value assigned to these (path parameters, query parameters, or headers) can be mapped to workflow input properties by configuring the corresponding workflow input properties in your workflow. To enable this mapping, create workflow input properties that match the names of the parameters or headers you expect to receive. Martini will automatically map incoming values to these properties if the names match exactly.

Path Parameters

  1. Create a workflow input property in your workflow. See Workflows Inputs and Outputs.
  2. Use the exact name of your workflow input property as a path parameter by wrapping it in {} when configuring.

Example (Path Parameter):

  • Create a userId String property in the workflow input.
  • Set your webhook URL as: 
    1
    GET /notifications/{userId}
  • A request to GET /notifications/1 will map the value 1 to the workflow input's userId property.

Query Parameters

  1. Create a workflow input property in your workflow. See Workflows Inputs and Outputs.
  2. Use the workflow input property name as the query name. Any value assigned via query will be mapped to the workflow input property if names match exactly.
  3. You can test this mapping directly in the Workflow Designer. See Testing Your Webhook Trigger Node.

Example (Query Parameter):

  • Create a userId String property in the workflow input.
  • Send a request to: 
    1
    GET /notifications?userId=123
  • The value 123 will be mapped to the workflow input's userId property.

Important: For URL Path Parameters and Query Names make sure they match exactly the workflow input property names you want the values mapped to.

Webhook Trigger Input Properties

When a workflow is triggered by a webhook request, Martini automatically creates two trigger input properties: $request and $response. These special properties provide direct access to the details of the incoming HTTP request and HTTP response. You can use them in your workflow logic to read request data, set response values, and handle integration scenarios beyond simple input mapping. The tables below summarize the available fields for each trigger input property.

$request Properties

Property Type Description
$request.method String HTTP method of the incoming request (e.g., GET, POST)
$request.uri String URI of the incoming request
$request.contentType String Content-Type header value of the request
$request.headers Array List of request headers
$request.cookies Array List of request cookies
$request.parameters Object Query parameters and path parameters as key-value pairs
$request.body Any Request body content (JSON, form-data, etc.)
$request.config Object Request configuration (timeouts, redirects, etc.)
$request.encoded Boolean Indicates if the request body is encoded

$response Properties

Property Type Description
$response.responseCode Number HTTP response code to return
$response.headers Array List of response headers
$response.cookies Array List of response cookies
$response.content Any Response body content to return

Example usage:

  • Access a request header value: $request.headers['X-Auth-Token']
  • Access a query parameter: $request.parameters['userId']
  • Access the request body: $request.body
  • Access the response content: $response.content

You can perform these actions using set expressions in nodes such as Map, Script, or Invoke Function nodes within your workflow. For more details, see Workflow Map Node, Workflow Script Node, and Workflow Function Node.

Mapping Workflow Output to HTTP Response

To control the HTTP response sent back to the client when your workflow is triggered by a webhook, follow these steps:

Step 1: Create an Output Property

Define an output property in your workflow using the Workflow Input/Output panel. This property will hold the response data that gets sent back to the client. See Workflow Inputs & Outputs for detailed instructions.

Step 2: Build Your Response Data

You have two main approaches to populate your output property:

The $response trigger input property contains standard HTTP response fields (responseCode, headers, cookies, content). This approach gives you full control over the HTTP response:

  1. Set response values using a Map Node (by dragging values to the $response properties) or Script Node (using the following script): 

    1
2
    $response.responseCode = 200
$response.content = ["status": "success", "userId": $request.parameters['userId']]

  2. Map $response to your output property using a Map Node:

    • Drag $response from the left panel to your output property in the right panel

      Ensure your output property is an Object type

Option B: Direct Mapping

Alternatively, map values directly to your output property using a Map Node without using $response.

Result

Your webhook-triggered workflow logic now returns an HTTP response mapped from the workflow's output properties, including the status code, headers, and body content.

💡 Pro Tip: Using $response ensures your webhook returns proper HTTP status codes and headers, making it easier for external systems to handle your responses correctly.

Testing Your Webhook Trigger Node

Martini Designer provides two ways to test your Webhook Trigger Node:

Simulating Webhook Events in Workflow Designer

Martini Designer lets you quickly simulate webhook events without any external setup:

  1. Right-click the Webhook Trigger Node and click Run. This will automatically select it in the Trigger dropdown in the Run Workflow Configuration dialog.

  2. Use the Trigger Mock Data Configuration to simulate requests. See Configuration Properties for more details:

    • Set HTTP Method
    • Enter URL Path (with path parameter values)
    • Add Query parameters, Headers, and Body

Expected result:
Your workflow executes as if it received a real webhook event.

Testing with HTTP Client (Real HTTP Requests)

To fully test the behavior of the Webhook Trigger Node as an actual HTTP endpoint:

  1. Right-click the Webhook Trigger Node and click "Invoke in HTTP Client".
  2. The built-in HTTP Client (similar to Postman, but embedded in Martini) will open with the request URL and HTTP method automatically populated based on your Webhook Trigger Node configuration.
  3. Add your headers and body content as needed.
  4. Click Send to submit the request, just as you would in a Postman request.
  5. Observe the workflow's response and behavior in the HTTP Client interface.

For more details on using HTTP Client, see Creating Requests in HTTP Client.

Expected result:
Your workflow is triggered by a real HTTP request, letting you verify the complete webhook integration end-to-end.

Configuration Properties

Property Example Value What It Controls
HTTP Method GET, POST Which HTTP methods will trigger the workflow
URL Path /notifications/{id} The endpoint path for the webhook
Query Parameters userId=123 Data mapped to workflow input properties
Headers X-Auth-Token: abc Data mapped to workflow input properties
Body JSON, form-data Request payload mapped to workflow input properties

Important: For URL Path Parameters, Query Names, and Header Names, make sure they match exactly the workflow input property names you want the values mapped to. See Using Workflow Input Properties with your Webhook Trigger Node.

Webhook trigger vs. REST API Operation

Webhook Trigger Nodes are a simple and limited way to expose a workflow to receive HTTP requests. They offer:

  • Basic HTTP endpoint configuration with minimal setup
  • No built-in authentication mechanisms
  • Single operation per webhook endpoint
  • Ideal for simple integration scenarios with third-party systems

REST API Operations are fully-featured implementations that provide:

  • Comprehensive API design with multiple endpoints and operations
  • Built-in authentication and security features
  • Advanced request/response handling and validation
  • Complete API documentation and testing capabilities

When to choose each:

  • Use Webhook Triggers for simple use cases requiring a single HTTP endpoint, particularly when integrating with third-party webhook providers (payment gateways, notification services, etc.), where a full REST API implementation would be excessive.
  • Use REST API Operations when you need comprehensive API functionality with multiple endpoints, authentication, or advanced features.

Troubleshooting

Problem Detection Cause Fix Affected Versions
Webhook not triggering Workflow does not execute Incorrect HTTP method or URL path Verify method and path match configuration v2.2+
Input property not mapped Value missing in workflow input Path/query/header name mismatch Ensure names match exactly v2.2+

Helpful Resources