Trigger WorqHat workflows by sending JSON data to them, allowing you to integrate workflow automation with your applications and respond to events in real-time. 
POST https://api.worqhat.com/api/workflows/trigger/{workflow-id}

​
What Does This Endpoint Do?

This endpoint allows you to start a workflow execution by sending structured JSON data. The workflow processes this data according to the steps you’ve defined in the WorqHat Workflow Builder, enabling automation based on your specific business logic.

​
When to Use JSON Payload Triggers

You’ll find this endpoint useful when you need to:
  • Integrate with applications: Send data from your applications to trigger automated processes
  • Respond to events: Start workflows when specific events occur in your systems
  • Process structured data: Pass complex data structures for processing by AI and other workflow steps
  • Customize workflow behavior: Dynamically control how workflows operate based on input parameters
  • Connect third-party services: Use webhooks to trigger workflows from external platforms

​
How It Works

  1. You send a POST request with your JSON payload to the workflow’s unique endpoint
  2. The workflow processes the data according to the steps you’ve defined
  3. You receive an immediate confirmation response with a tracking ID
  4. The workflow continues executing in the background

​
Prerequisites

Before triggering a workflow, you’ll need:
  1. A WorqHat account with workflow creation permissions
  2. An API key with appropriate permissions
  3. The workflow ID of the workflow you want to trigger

​
Request Parameters

​
payload
object
required
The JSON data to send to the workflow. This can be any valid JSON object structure that your workflow is designed to process.Example: Customer data, order information, configuration settings, etc.
​
Authorization
string
required
Your API key in the format: Bearer YOUR_API_KEY
​
Content-Type
string
required
Must be set to application/json
​
workflow-id
string
required
The unique identifier (UUID) of the workflow you want to trigger

​
Response Fields Explained

​
success
boolean
Indicates whether the workflow was successfully triggered
​
message
string
A human-readable message describing the result of the operation
​
analytics_id
string
A unique identifier for tracking this specific workflow execution. You can use this ID to query the status or results of the workflow later.
​
timestamp
string
ISO 8601 timestamp indicating when the workflow was triggered
​
data
object
Additional data about the workflow execution
​
data.workflow_status
string
The initial status of the workflow, typically “started”

​
Code Examples

​
Example 1: Customer Onboarding Workflow

This example shows how to trigger a workflow that processes new customer information. 
import Worqhat from 'worqhat';

// Initialize the WorqHat client
const client = new Worqhat({
  apiKey: process.env.WORQHAT_API_KEY, // Always use environment variables for API keys
});

// Customer data to be processed by the workflow
const customerData = {
  name: "Jane Smith",
  email: "jane.smith@example.com",
  plan: "premium",
  company: "Acme Inc.",
  preferences: {
    notifications: true,
    newsletter: false,
    productUpdates: true
  }
};

async function onboardNewCustomer() {
  try {
    // Trigger the onboarding workflow with customer data
    const response = await client.flows.triggerWithPayload(
      'workflow-id-for-customer-onboarding',
      { body: customerData }
    );
    
    console.log(`Onboarding workflow started! Tracking ID: ${response.analytics_id}`);
    
    // You can store this analytics_id to check the status later
    return response;
  } catch (error) {
    console.error('Error triggering onboarding workflow:', error);
    // Handle the error appropriately
  }
}

onboardNewCustomer();

​
Example Response

Here’s what a successful response looks like when triggering a workflow: 
{
  "success": true,
  "message": "Workflow triggered successfully",
  "analytics_id": "wf-exec-12345-abcde-67890",
  "timestamp": "2023-07-24T15:30:45Z",
  "data": {
    "workflow_status": "started"
  }
}

​
Error Handling

When triggering workflows, it’s essential to implement proper error handling to ensure your application can gracefully handle failures.

​
Common Error Scenarios

  • Always store your API keys securely and never expose them in client-side code
  • Consider what data you’re sending to workflows and ensure sensitive information is handled appropriately
  • Use HTTPS for all API communications

​
Error Handling

Implement robust error handling to manage cases where:
  • The workflow trigger request fails
  • The workflow ID is invalid
  • The API key doesn’t have sufficient permissions
  • The JSON payload is malformed
try {
  const response = await client.flows.triggerWithPayload(workflowId, { body: data });
  // Handle success
} catch (error) {
  if (error.status === 401) {
    console.error('Authentication failed. Check your API key.');
  } else if (error.status === 404) {
    console.error('Workflow not found. Verify the workflow ID.');
  } else if (error.status === 400) {
    console.error('Invalid request format:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Payload Size Limits

Be mindful of payload size limits when sending data to workflows:
  • The maximum payload size is 10MB
  • For larger datasets, consider using file uploads or breaking the data into smaller chunks

​
Real-World Use Cases

​
E-commerce Order Processing

Trigger a workflow when a new order is placed to handle inventory updates, payment processing, and shipping notifications: 
await client.flows.triggerWithPayload('order-processing-workflow-id', {
  body: {
    orderId: "ORD-12345",
    customer: {
      id: "CUST-789",
      name: "Alex Johnson",
      email: "alex@example.com"
    },
    items: [
      { productId: "PROD-001", quantity: 2, price: 29.99 },
      { productId: "PROD-042", quantity: 1, price: 49.99 }
    ],
    shipping: {
      method: "express",
      address: {
        street: "123 Main St",
        city: "Boston",
        state: "MA",
        zip: "02108"
      }
    },
    payment: {
      method: "credit_card",
      transactionId: "TXN-5678"
    }
  }
});

​
Data Analysis Pipeline

Trigger a workflow to analyze data and generate reports: 
await client.flows.triggerWithPayload('data-analysis-workflow-id', {
  body: {
    datasetId: "DS-456",
    analysisParameters: {
      timeRange: { start: "2025-01-01", end: "2025-07-31" },
      metrics: ["revenue", "user_growth", "conversion_rate"],
      segmentation: ["region", "device_type", "user_tier"],
      comparisonPeriod: "previous_quarter"
    },
    outputFormat: "pdf",
    notifyEmail: "reports@yourcompany.com"
  }
});

​
Conclusion

Triggering workflows with JSON payloads provides a flexible way to integrate WorqHat’s automation capabilities into your applications. By following the patterns and practices outlined in this guide, you can create powerful, event-driven systems that respond to your business needs in real-time. For more advanced use cases, consider exploring workflow chaining (triggering workflows from other workflows) and combining JSON payload triggers with file upload triggers for comprehensive data processing solutions.