Webhooks 🔔

Stay in the loop with real-time updates about your workflow execution!

🚀 TLDR: Add a webhookUrl when executing your workflow and we'll send real-time updates about node execution, results, and errors. Perfect for monitoring and automation!

View Complete Webhook Payload Schema

Adding Webhooks ✨

Getting started is super simple! Just add your webhook URL when executing your workflow:

import { GraphCompose } from '@graphcompose/sdk'

const client = new GraphCompose()

// Start execution and get workflowId
const { workflowId } = await client.execute({
  context: { batch_size: 1000 },
  webhookUrl: "https://api.your-app.com/webhooks"
});

Webhook Events 📬

Your webhook endpoint will receive two types of events:

Node Events 🔄

Sent after each node execution:

{
  workflowId: "workflow_123",  // Workflow instance ID
  runId: "run_456",           // Temporal run ID
  type: "node",
  data: {
    timestamp: 1709347200000,
    nodeId: "process_payment",
    nodeType: "http",
    executionState: "executed",  // Current node execution state
    result: {                    // Only present if execution succeeded
      // Node execution result
    },
    error: undefined            // Only present if execution failed
  }
}

Completion Events 🏁

Sent when the workflow completes:

{
  workflowId: "workflow_123",  // Workflow instance ID
  runId: "run_456",           // Temporal run ID
  type: "completion",
  data: {
    timestamp: 1709347200000,
    result: {                  // Final workflow results
      // Results from all nodes
    },
    error: undefined          // Only present if workflow failed
  }
}

Error Example 🚨

When a node fails, the error data looks like this:

{
  workflowId: "workflow_123",
  runId: "run_456",
  type: "node",
  data: {
    timestamp: 1709347200000,
    nodeId: "process_payment",
    nodeType: "http",
    executionState: "executed_and_failed",
    error: {
      message: "Payment processing failed",  // Error message
      type: "VALIDATION_ERROR",             // Error type if available
      details: {                           // Additional error details
        // Error-specific information
      }
    }
  }
}

Best Practices 💡

Keep your webhooks reliable and efficient:

⚡ Make your webhook endpoints fast and responsive
🔄 Process webhooks asynchronously when possible
📝 Log webhook events for debugging and monitoring
🎯 Keep webhook processing logic simple and focused
🛡️ Handle webhook failures gracefully in your application

💡 Pro tip: Your webhook endpoint should return quickly (HTTP 2xx) to acknowledge receipt. Webhook failures are logged but won't affect your workflow execution.

Workflow API Reference