Webhook Trigger

The Webhook Trigger allows you to start workflows from external applications, services, or scripts by making HTTP requests to a unique webhook URL. This enables powerful integrations and real-time automation triggered by events from other systems.

When to Use It

Trigger workflows when data changes in external systems
Integrate with third-party applications and services
Start workflows from custom scripts or applications
Build real-time automation pipelines
Process incoming data from APIs or webhooks
Create event-driven workflows
Connect legacy systems to your automation

How It Works

The Webhook Trigger generates a unique URL and security key for your workflow. When external systems make HTTP POST requests to this URL with the correct authentication, your workflow is triggered instantly with the request data available for processing.

Security

Each webhook uses a unique authentication key (x-webhook-key header)
Keys can be regenerated at any time for security
Only POST requests with valid keys trigger workflows
HTTPS encryption protects data in transit

Setup

Step 1: Generate Webhook Credentials

Add the Webhook Trigger node to your workflow
Click “Generate Webhook Key” to create authentication credentials
Copy the Webhook URL and Webhook Key for use in your external system

Step 2: Extract Specific Keys (Optional)

Define the keys you expect in your webhook payload to make them easily accessible as individual outputs:

In the “Extract Specific Keys” field, add the JSON keys you expect to receive
Enter one key per line (e.g., user_id, email, order_id)
These keys will automatically appear as separate outputs you can reference in later nodes
If a key doesn’t exist in the actual payload, it will return null
The complete payload is always available regardless of which keys you extract

Example: If you expect webhooks with this structure:

{
  "user_id": "12345",
  "email": "customer@example.com",
  "order_id": "ORD-789",
  "amount": 99.99
}

Add these keys: user_id, email, order_id, amount This makes it easier to reference specific values in your workflow without needing to parse the full payload.

Step 3: Configure External System

Use the generated URL and key to make HTTP requests from your external application:

curl -X POST https://www.markifact.com/api/webhooks/your-workflow-id \
  -H "x-webhook-key: wh_your-generated-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "12345",
    "event": "order_completed",
    "amount": 99.99,
    "email": "customer@example.com"
  }'

Step 4: Use Webhook Data

The JSON data sent in the request body becomes available as outputs which you can use in subsequent workflow nodes:

Full Payload: Access all webhook data at once
Individual Keys: If you defined specific keys to extract, each appears as a separate output for easy reference

Making Webhook Requests

Required Headers

Header	Value	Description
`x-webhook-key`	Your generated key	Authentication (required)
`Content-Type`	`application/json`	Data format (recommended)

Request Method

Only POST requests are supported
GET, PUT, DELETE, and other methods will be rejected

Request Body

Send any JSON data structure
All data will be available in the next workflow step
Maximum payload size: 1MB
Data can include nested objects and arrays

Example Requests

Simple Data:

curl -X POST https://www.markifact.com/api/webhooks/your-workflow-id \
  -H "x-webhook-key: YOUR_WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "action": "signup"
  }'

From JavaScript:

fetch('https://www.markifact.com/api/webhooks/your-workflow-id', {
  method: 'POST',
  headers: {
    'x-webhook-key': 'YOUR_WEBHOOK_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: '12345',
    eventType: 'purchase',
    data: {
      productId: 'PROD-789',
      amount: 99.99
    }
  })
});

From Python:

import requests
import json

url = "https://www.markifact.com/api/webhooks/your-workflow-id"
headers = {
    "x-webhook-key": "YOUR_WEBHOOK_KEY",
    "Content-Type": "application/json"
}
data = {
    "user_id": "12345",
    "event": "data_updated",
    "timestamp": "2024-10-22T10:30:00Z",
    "payload": {
        "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUq",
        "rows_affected": 25
    }
}

response = requests.post(url, headers=headers, data=json.dumps(data))

Outputs

The Webhook Trigger provides flexible output options based on your configuration:

Output	Type	Description
Full Payload	Object	Complete JSON data from the webhook request body
Extracted Keys	Various	Individual outputs for each key you specified in “Extract Specific Keys”

Output Examples

Without Extracted Keys:

Only Full Payload is available
Access nested data using dot notation: data.user_id, data.order.total

With Extracted Keys: If you extracted user_id, email, and order_id, you’ll see:

Full Payload - Complete webhook data
user_id - Direct access to the user_id value
email - Direct access to the email value
order_id - Direct access to the order_id value

Using Webhook Data

Option 1: Use Extracted Keys (Recommended)

Define the keys you need in the “Extract Specific Keys” field
Reference them directly in other nodes without dot notation
Example: Use {{user_id}} instead of {{data.user_id}}
Cleaner and easier to work with in most cases

Option 2: Use Full Payload

Access any field using dot notation like data.user_id or data.order.total
Useful when webhook structure varies or contains dynamic keys
Process arrays using List Tools (e.g., data.items)
Good for complex nested structures

Option 3: Process with Python

Use the Python Code node to transform the full payload
Extract, calculate, or restructure data as needed
See the Processing Webhook Payloads section below for examples

Processing Webhook Payloads

Once your webhook receives data, you have complete flexibility in how to process it using Markifact’s nodes: Python Node Processing:

Use the Python Code node to parse, transform, and manipulate the webhook payload
Perform complex data calculations, validations, or transformations
Extract specific fields, combine data, or restructure the payload format
Example: Parse timestamps, calculate totals, validate email formats, or clean data

Data Manipulation Options:

List Tools: Process arrays within the webhook payload
Text Tools: Format strings, extract patterns, or modify text fields
Conditional Logic: Route data based on webhook payload values
Data Transformation: Convert formats, merge with other data sources, or enrich the payload

Example Python Processing:

# Access the webhook payload
webhook_data = inputs['data']

# Extract and process specific fields
user_email = webhook_data.get('email', '').lower().strip()
order_total = float(webhook_data.get('amount', 0))

# Perform calculations
tax_amount = order_total * 0.08
final_total = order_total + tax_amount

# Create processed output
processed_data = {
    'customer_email': user_email,
    'subtotal': order_total,
    'tax': tax_amount,
    'total': final_total,
    'processed_at': datetime.now().isoformat()
}

processed_data

This flexibility allows you to build sophisticated data processing pipelines that start with webhook triggers and transform the data exactly as needed for your specific use case.

Response Handling

Success Response

When the webhook is successfully received and the workflow is triggered:

HTTP Status: 200 OK
Response Body: {"status": "success", "message": "Webhook received"}

Error Responses

Status Code	Description	Common Causes
`400 Bad Request`	Invalid request format	Missing or malformed JSON
`401 Unauthorized`	Authentication failed	Missing or incorrect `x-webhook-key`
`405 Method Not Allowed`	Wrong HTTP method	Using GET, PUT, DELETE instead of POST
`413 Payload Too Large`	Request body too large	Payload exceeds 1MB limit
`429 Too Many Requests`	Rate limit exceeded	Too many requests in short period

Troubleshooting

Webhook Not Triggering

Verify the webhook URL is correct
Check that x-webhook-key header is included and correct
Ensure you’re using POST method, not GET
Confirm Content-Type is set to application/json
Make sure the workflow is ACTIVE. Check toggle status in the workflow editor.

Invalid Key Errors

Regenerate the webhook key if it may have been compromised
Update your external system with the new key
Check for extra spaces or characters in the key

Payload Issues

Verify JSON format is valid
Check payload size is under 1MB
Ensure special characters are properly encoded

Extracted Key Shows Null

Verify the key name matches exactly (case-sensitive)
Check that the key exists in your webhook payload
Ensure the payload is valid JSON
Remember: If a key doesn’t exist, it returns null (this is expected behavior)

Get Started

Guides

Nodes

When to Use It

How It Works

Security

Setup

Step 1: Generate Webhook Credentials

Step 2: Extract Specific Keys (Optional)

Step 3: Configure External System

Step 4: Use Webhook Data

Making Webhook Requests

Required Headers

Request Method

Request Body

Example Requests

Outputs

Output Examples

Using Webhook Data

Processing Webhook Payloads

Response Handling

Success Response

Error Responses

Troubleshooting

Webhook Not Triggering

Invalid Key Errors

Payload Issues

Extracted Key Shows Null

Get Started

Guides

Nodes

​When to Use It

​How It Works

​Security

​Setup

​Step 1: Generate Webhook Credentials

​Step 2: Extract Specific Keys (Optional)

​Step 3: Configure External System

​Step 4: Use Webhook Data

​Making Webhook Requests

​Required Headers

​Request Method

​Request Body

​Example Requests

​Outputs

​Output Examples

​Using Webhook Data

​Processing Webhook Payloads

​Response Handling

​Success Response

​Error Responses

​Troubleshooting

​Webhook Not Triggering

​Invalid Key Errors

​Payload Issues

​Extracted Key Shows Null

When to Use It

How It Works

Security

Setup

Step 1: Generate Webhook Credentials

Step 2: Extract Specific Keys (Optional)

Step 3: Configure External System

Step 4: Use Webhook Data

Making Webhook Requests

Required Headers

Request Method

Request Body

Example Requests

Outputs

Output Examples

Using Webhook Data

Processing Webhook Payloads

Response Handling

Success Response

Error Responses

Troubleshooting

Webhook Not Triggering

Invalid Key Errors

Payload Issues

Extracted Key Shows Null