Webhook In¶

Trigger Task - The entry point for your automation workflows

The Webhook In task is a trigger task that receives incoming data from external applications via HTTP POST requests. It creates a unique URL endpoint that external services can call to start your workflow.

When to Use

Use Webhook In when you need to:

Receive real-time data from external services
Trigger workflows based on external events
Create API endpoints for third-party integrations
Build custom webhooks for your applications

How It Works¶

sequenceDiagram
    participant External as External Service
    participant Webhook as Webhook In Task
    participant Workflow as Your Workflow

    External->>Webhook: POST request with data
    Webhook->>Workflow: Trigger workflow
    Workflow->>Workflow: Process data
    Workflow-->>External: Response (optional)

Quick Start¶

Add a Webhook In task as the first task in your workflow
Copy the Production URL from the task settings
Configure your external service to send POST requests to this URL
The webhook data will be available to all subsequent tasks

[SCREENSHOT NEEDED: Webhook In task panel showing Production URL and Test URL fields]

Task Settings¶

Task Name¶

Give your webhook a descriptive name that indicates its purpose.

Example: Customer Order Webhook, Lead Form Submission, Payment Notification

Webhook URLs¶

Every Webhook In task provides two unique URLs:

Production URL¶

https://api.basecloudglobal.com/webhook/6ceb34ab478cb8cd723568

What it does: - Logs the incoming data as an event - Runs the trigger task and executes all child tasks - Use this URL in your live integrations

When to use: - Integration is fully tested and working - Ready for real customer/production data - Live environment is stable

Test URL¶

https://api.basecloudglobal.com/webhook-test/6ceb34ab478cb8cd723568

What it does: - Logs the incoming data (for testing/debugging) - Does NOT run child tasks - only the trigger task runs - Allows you to see what data is being received without processing

When to use: - Testing new integrations - Debugging data format issues - Validating incoming data structure - Development and staging environments

Test URL vs Production URL

The Test URL only logs data and runs the trigger task itself. It does NOT execute any child tasks in your workflow. Use it to verify you're receiving the correct data, then switch to the Production URL to actually process that data through your workflow.

Response Settings¶

Configure how your webhook responds to the calling service.

Response Type Options¶

1. Respond Immediately with Custom Response¶

Returns your custom response instantly to the caller, then processes the workflow in the background.

Timeline:

External Service → Webhook → Immediate Response (< 1 second)
                            ↓
                    Workflow continues in background

When to use: - Long-running workflows (> 30 seconds) - Caller doesn't need workflow results - External service has strict timeout limits (like Stripe) - Want to acknowledge receipt quickly

Example Response:

{
  "success": true,
  "message": "Webhook received"
}

With dynamic data from incoming request:

{
  "received": true,
  "customer": "{{customer_name}}",
  "order_id": "{{order_id}}"
}

Use Handlebars for Dynamic Responses

You can include data from the incoming POST request using {{fieldname}} syntax. For example, if the caller sends {"order_id": "12345"}, you can use {{order_id}} in your response.

2. Redirect to URL¶

Returns an HTTP 302 redirect to the specified URL.

Timeline:

External Service → Webhook → 302 Redirect to URL
                            ↓
                    Workflow continues in background

When to use: - Form submissions that need to redirect users - Payment confirmations that redirect to thank you pages - User needs to be sent to a different page after submission

Example:

https://yourwebsite.com/thank-you

With dynamic data in URL:

https://yourwebsite.com/confirmation?order={{order_id}}&name={{customer_name}}

User Experience

The user will be immediately redirected while your workflow processes in the background. Great for form submissions where you want to show a thank you page right away.

3. Respond After Workflow Completes¶

Waits for all child tasks to finish executing, then returns a response with data from the entire workflow.

Timeline:

External Service → Webhook → Wait for workflow...
                            ↓
                    All tasks execute
                            ↓
                    Response with task outputs

When to use: - Caller needs confirmation of successful processing - Need to return processed data (like IDs created during workflow) - Workflow completes quickly (< 30 seconds) - Building synchronous API endpoints

Example Response:

{
  "status": "processed",
  "client_id": "{{task_35529_client_id}}",
  "full_name": "{{task_35530_full_name}}",
  "email_sent": "{{task_35531_run}}"
}

Accessing Task Outputs

Use {{task_TASKID_fieldname}} to include output from any task in your workflow. Each task's output fields are available as variables. For example, if task 35529 creates a customer and outputs client_id, reference it as {{task_35529_client_id}}.

Delay Task Behavior

Important: If your workflow contains a Delay task, the webhook will respond immediately with data available up to that point. It won't wait for tasks after the delay. This prevents long timeout issues.

Custom Response Body¶

Define exactly what JSON, XML, or plain text is returned to the caller.

Available for: - Respond Immediately (with incoming data) - Respond After Workflow Completes (with task outputs)

Simple JSON Response¶

{
  "success": true
}

Response with Incoming Data (Immediate)¶

When using Respond Immediately, you can include fields from the incoming POST request:

{
  "received": true,
  "order_id": "{{order_id}}",
  "customer": "{{customer_name}}",
  "timestamp": "{{$now}}"
}

If the incoming request contains:

{
  "order_id": "ORD-12345",
  "customer_name": "John Doe"
}

The response will be:

{
  "received": true,
  "order_id": "ORD-12345",
  "customer": "John Doe",
  "timestamp": "2026-02-04T10:30:00Z"
}

Response with Task Outputs (After Workflow)¶

When using Respond After Workflow Completes, you can include output from any task:

{
  "status": "processed",
  "customer_id": "{{task_35529_client_id}}",
  "invoice_number": "{{task_35530_invoice_number}}",
  "email_sent": "{{task_35531_run}}",
  "total_amount": "{{task_35532_total}}"
}

How to find task IDs: 1. Open your workflow in BaseCloud 2. Click on any task 3. The task ID is shown in the task details panel 4. Use format: {{task_TASKID_fieldname}}

Common task output fields: - {{task_TASKID_run}} - Whether task succeeded (true/false) - {{task_TASKID_run_text}} - Status message - {{task_TASKID_FIELDNAME}} - Any field output by the task

XML Response¶

You can return XML instead of JSON:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <success>true</success>
  <order_id>{{order_id}}</order_id>
  <status>processed</status>
</response>

Plain Text Response¶

Simple text responses are also supported:

Order {{order_id}} received successfully for {{customer_name}}

How Task Output Works¶

The Webhook In trigger task receives incoming data and passes it directly through as output. This makes all incoming fields available to child tasks.

Data Flow¶

graph LR
    A[External Service] -->|POST data| B[Webhook In Task]
    B -->|All fields become output| C[Child Task 1]
    C -->|Can access webhook data| D[Child Task 2]
    D -->|Can access webhook data| E[Child Task 3]

Example¶

Incoming POST data:

{
  "customer_name": "Jane Smith",
  "email": "jane@example.com",
  "order_total": 299.99,
  "items": ["Product A", "Product B"]
}

Available in all child tasks:

{{task_46055_customer_name}}  → "Jane Smith"
{{task_46055_email}}          → "jane@example.com"
{{task_46055_order_total}}    → 299.99
{{task_46055_items}}          → ["Product A", "Product B"]

Task Status Variables:

{{task_46055_run}}            → true
{{task_46055_run_text}}       → "Inbound data received and processed successfully"

Accessing Nested Data¶

The Webhook In task automatically flattens nested JSON structures for easy access. You have two ways to reference the data:

Option 1: Flattened Fields (Recommended)¶

If the incoming data is nested:

{
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "order": {
    "id": "ORD-123",
    "total": 150.00
  },
  "items": [
    {"name": "Product A", "quantity": 2, "price": 29.99},
    {"name": "Product B", "quantity": 1, "price": 49.99}
  ]
}

Access flattened fields using underscores:

{{task_46171_customer_name}}      → "John Doe"
{{task_46171_customer_email}}     → "john@example.com"
{{task_46171_order_id}}           → "ORD-123"
{{task_46171_order_total}}        → 150.00
{{task_46171_items_0_name}}       → "Product A"
{{task_46171_items_0_quantity}}   → 2
{{task_46171_items_1_name}}       → "Product B"

Option 2: JSON Notation¶

Access the original JSON structure directly:

{{task_46171.JSON.customer.name}}    → "John Doe"
{{task_46171.JSON.order.id}}         → "ORD-123"
{{task_46171.JSON.items[0].name}}    → "Product A"
{{task_46171.JSON.items[1].name}}    → "Product B"

Which One to Use?

Flattened fields are simpler and work in most tasks. Use JSON notation when you need to loop through arrays or access deeply nested structures in advanced scenarios.

Real-World Examples¶

Example 1: E-commerce Order Processing (Immediate Response)¶

Scenario: Shopify sends order data. We need to acknowledge receipt quickly, then process in background.

Workflow:

Webhook In → Create Customer → Update Inventory → Send Confirmation Email

Webhook Configuration:

Response Type: Respond Immediately with Custom Response

Custom Response:

{
  "success": true,
  "order_received": "{{order_id}}",
  "timestamp": "{{$now}}"
}

Why Immediate Response: - Shopify has timeout limits - Processing might take 10-20 seconds - Don't want Shopify to retry thinking it failed

Example 2: Synchronous API Endpoint (After Workflow)¶

Scenario: Create a customer and return their ID immediately to the caller.

Workflow:

Webhook In → Create Customer in CRM → Send Welcome Email

Webhook Configuration:

Response Type: Respond After Workflow Completes

Custom Response:

{
  "success": true,
  "customer_id": "{{task_35529_client_id}}",
  "customer_number": "{{task_35529_client_number}}",
  "email_sent": "{{task_35530_run}}"
}

Why After Workflow: - Caller needs the customer ID immediately - Workflow completes in < 5 seconds - Synchronous API behavior expected

Example 3: Form Submission with Redirect¶

Scenario: Contact form on website needs to redirect user to thank you page.

Workflow:

Webhook In → Add to CRM → Send Notification to Sales Team

Webhook Configuration:

Response Type: Redirect to URL

Redirect URL:

https://yourwebsite.com/thank-you?name={{first_name}}&ref={{form_id}}

Why Redirect: - User experience - show thank you page immediately - Form data processes in background - Professional user flow

Example 4: Payment Webhook with Workflow Data¶

Scenario: Stripe payment confirmed, need to return invoice details.

Workflow:

Webhook In → Verify Payment → Create Invoice → Send Receipt

Webhook Configuration:

Response Type: Respond After Workflow Completes

Custom Response:

{
  "payment_status": "confirmed",
  "invoice_id": "{{task_35531_invoice_id}}",
  "invoice_number": "{{task_35531_invoice_number}}",
  "receipt_sent": "{{task_35532_run}}",
  "amount": "{{amount}}",
  "customer": "{{customer_email}}"
}

Testing Your Webhook¶

Test URL vs Production URL Testing¶

Step 1: Test with Test URL first

curl -X POST \
  https://api.basecloudglobal.com/webhook-test/YOUR_TOKEN \
  -H 'Content-Type: application/json' \
  -d '{"customer_name": "Test User", "email": "test@example.com"}'

What happens: - Data is logged - Trigger task runs (you can see the data received) - Child tasks DO NOT run - Great for verifying data format

Step 2: Test with Production URL

curl -X POST \
  https://api.basecloudglobal.com/webhook/YOUR_TOKEN \
  -H 'Content-Type: application/json' \
  -d '{"customer_name": "Test User", "email": "test@example.com"}'

What happens: - Data is logged - Trigger task runs - ALL child tasks execute - Full workflow processes

Using Postman¶

Create New Request
Method: POST
URL: Your Test URL (to start)
Set Headers
```
Content-Type: application/json
```

Add Body (raw JSON)

{
  "customer_name": "John Doe",
  "email": "john@example.com",
  "order_id": "ORD-12345",
  "amount": 299.99
}

[SCREENSHOT NEEDED: Postman interface showing POST request to webhook URL with JSON body]

Send and Check
Check response from webhook
View workflow execution in BaseCloud
Verify data is accessible in tasks

Using JavaScript (Frontend)¶

async function submitToWebhook(data) {
  try {
    const response = await fetch('https://api.basecloudglobal.com/webhook/YOUR_TOKEN', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data)
    });

    const result = await response.json();
    console.log('Success:', result);
    return result;
  } catch (error) {
    console.error('Error:', error);
  }
}

// Usage
submitToWebhook({
  customer_name: 'Jane Smith',
  email: 'jane@example.com',
  order_total: 150.00
});

Using PHP (Backend)¶

<?php
$data = [
    'customer_name' => 'John Doe',
    'email' => 'john@example.com',
    'order_id' => 'ORD-12345'
];

$ch = curl_init('https://api.basecloudglobal.com/webhook/YOUR_TOKEN');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Best Practices¶

✓ Do¶

Test with Test URL first - Verify data format before going live
Use Production URL for live traffic - Once testing is complete
Choose appropriate response type - Immediate for long workflows, After Workflow for synchronous APIs
Include handlebars in responses - Make responses dynamic with incoming or task data
Validate incoming data - Add validation tasks after the webhook
Keep webhook URLs private - Don't expose them in public repositories
Document your webhooks - Keep notes on what each webhook is used for
Set up error handling - Add error notification tasks

✗ Don't¶

Don't use Production URL for testing - Always test with Test URL first
Don't use "After Workflow" for long processes - Caller will timeout (use Immediate instead)
Don't ignore the Delay task warning - Responses return early if Delay is encountered
Don't use GET requests - Webhooks only accept POST
Don't forget Content-Type header - Always send Content-Type: application/json
Don't expose sensitive data in responses - Be careful what you return to caller

Troubleshooting¶

Webhook Not Triggering¶

Check these first:

URL Correctness
✓ Using the correct webhook token
✓ Using POST method (not GET)
✓ Using Test URL vs Production URL appropriately
Workflow Status
✓ Workflow is published
✓ Workflow is active (not paused)

Test Isolation

# Test with cURL to isolate the issue
curl -X POST https://api.basecloudglobal.com/webhook-test/YOUR_TOKEN \
  -H 'Content-Type: application/json' \
  -d '{"test": "data"}'

Solution: - Check workflow execution logs in BaseCloud - Verify the URL being called by external service - Test with Postman to confirm webhook works

Data Not Accessible in Child Tasks¶

Common causes:

Using Test URL - Test URL doesn't run child tasks
Solution: Switch to Production URL
Wrong variable name
Wrong: {{task_46055_customerName}}
Right: {{task_46055_customer_name}}
Solution: Check exact field names in webhook logs
Nested object access
Wrong: {{task_46055_customer}}
Right: {{task_46055_customer.name}}
Solution: Use dot notation for nested fields

Debugging:

1. Check webhook logs to see received data
2. Use {{task_46055_run_text}} to verify trigger ran
3. Test variable names in a simple Email task
4. Verify JSON structure being sent

Timeout Issues¶

Symptoms: - External service reports timeout - Workflow processes but caller doesn't get response

Causes: 1. Workflow too long - Takes > 30 seconds 2. Using "After Workflow" response type - Caller timeout limit reached 3. Delay task in workflow - Causes early response

Solutions:

Option 1: Change to Immediate Response

{
  "received": true,
  "message": "Processing in background"
}

Option 2: Optimize Workflow - Remove unnecessary delays - Simplify complex tasks - Consider splitting into multiple workflows

Option 3: Increase Caller Timeout - If possible, configure external service timeout to 60+ seconds

Response Not Returning Expected Data¶

Using "After Workflow" response type but getting empty fields?

Check: 1. Task ID is correct - View task details in BaseCloud to find actual task ID - Use: {{task_EXACT_ID_fieldname}}

Field name exists
Check task output in execution logs
Field names are case-sensitive
Delay task in workflow
If Delay task is reached, response returns immediately
Solution: Restructure workflow or use Immediate response type

Example Debug Response:

{
  "debug": "true",
  "task_35529_run": "{{task_35529_run}}",
  "task_35529_output": "{{task_35529_client_id}}",
  "raw_trigger_data": "{{customer_name}}"
}

External Service Not Receiving Response¶

Check: 1. Response format matches expected - Some services expect specific JSON structure - Check external service documentation

Content-Type is correct
Webhook returns application/json by default
XML responses need proper XML structure
HTTP status code
Success returns 200 OK
Redirects return 302 Found
Check external service logs for status received

Common Questions¶

What's the difference between Test URL and Production URL?

Test URL logs incoming data and runs the trigger task, but does NOT execute child tasks. Use it to verify you're receiving the correct data format.

Production URL logs data, runs the trigger task, AND executes all child tasks in your workflow. Use it for live integrations.

Can I use GET requests instead of POST?

No, Webhook In only accepts POST requests with JSON data in the body.

What happens if I use 'Respond After Workflow' with a Delay task?

The webhook will respond immediately with data available up to the Delay task. It won't wait for tasks after the delay to prevent timeout issues.

How do I include data from child tasks in the response?

Use the "Respond After Workflow Completes" response type and reference task outputs: {{task_TASKID_fieldname}}. For example: {{task_35529_client_id}}.

Can I return XML instead of JSON?

Yes! Just write your XML in the Custom Response field:

<?xml version="1.0"?>
<response>
  <success>true</success>
</response>

How do I access nested fields from the incoming data?

Use dot notation: {{task_46055_customer.name}} or {{task_46055_order.items[0]}}

What's the maximum payload size?

Standard HTTP limits apply (typically 10MB), which is sufficient for most use cases.

Can I trigger the webhook manually?

Yes! Use Postman, cURL, or any HTTP client to send POST requests to your webhook URL for testing.

How quickly does the workflow trigger?

Workflows trigger in real-time, typically within milliseconds of receiving the webhook request.

Can I use the same webhook URL for multiple external services?

Yes, but we recommend creating separate Webhook In tasks for different sources to keep workflows organized and easier to debug.

What happens if my workflow fails?

The webhook returns an error response, and you can review the error details in the workflow execution logs. Set up error notification tasks to get alerted.

Can I add authentication to my webhook?

While the webhook URL itself is secure (with a unique token), you can add additional validation by checking for specific headers or fields in the incoming data using an If Condition task.

How do I use handlebars in responses?

For incoming data: {{fieldname}} For task outputs: {{task_TASKID_fieldname}} For system variables: {{$now}}, {{$date}}, etc.

Webhook Out - Make outgoing API calls
Delay - Add time delays in your workflow
If Statement - Add conditional logic

Webhook In¶

How It Works¶

Quick Start¶

Task Settings¶

Task Name¶

Webhook URLs¶

Production URL¶

Test URL¶

Response Settings¶

Response Type Options¶

1. Respond Immediately with Custom Response¶

2. Redirect to URL¶

3. Respond After Workflow Completes¶

Custom Response Body¶

Simple JSON Response¶

Response with Incoming Data (Immediate)¶

Response with Task Outputs (After Workflow)¶

XML Response¶

Plain Text Response¶

How Task Output Works¶

Data Flow¶

Example¶

Accessing Nested Data¶

Option 1: Flattened Fields (Recommended)¶

Option 2: JSON Notation¶

Real-World Examples¶

Example 1: E-commerce Order Processing (Immediate Response)¶

Example 2: Synchronous API Endpoint (After Workflow)¶

Example 3: Form Submission with Redirect¶

Example 4: Payment Webhook with Workflow Data¶

Testing Your Webhook¶

Test URL vs Production URL Testing¶

Using Postman¶

Using JavaScript (Frontend)¶

Using PHP (Backend)¶

Best Practices¶

✓ Do¶

✗ Don't¶

Troubleshooting¶

Webhook Not Triggering¶

Data Not Accessible in Child Tasks¶

Timeout Issues¶

Response Not Returning Expected Data¶

External Service Not Receiving Response¶

Common Questions¶

Related Tasks¶

See Also¶