Initialize the WorqHat client

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/flows/trigger/{flowId}

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

Response Fields Explained

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 clientconst client = new Worqhat({apiKey: process.env.WORQHAT_API_KEY, // Always use environment variables for API keys});// Customer data to be processed by the workflowconst 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(    'flowId-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.