n8n Integration¶

Pisama integrates with n8n to detect failures in AI agent workflows built with the n8n workflow automation platform.

Why Monitor n8n Workflows?¶

n8n workflows increasingly incorporate AI/LLM nodes (OpenAI, Anthropic, LangChain). These workflows can exhibit the same failure patterns as code-based agents:

• Infinite loops from workflow retries or circular triggers
• State corruption from data transformation errors
• Hallucinations from bad LLM outputs propagating through nodes
• Token limit exhaustion on AI nodes

Integration Methods¶

Method 1: Webhook (Recommended)¶

The n8n workflow sends execution data to Pisama after each run. This provides real-time detection and works with both n8n Cloud and self-hosted instances.

Setup:

1. Register the workflow in Pisama first (this generates a webhook secret):

curl -X POST https://api.pisama.ai/api/v1/n8n/workflows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "abc123", "workflow_name": "My AI Workflow"}'

1. Add an HTTP Request node at the end of your n8n workflow to POST execution data to Pisama.

Important: The webhook body must include the full execution data structure (not just {{ $json }}). Use a Code node to construct the payload:

// Code node before HTTP Request
const executionId = $execution.id;
const workflowId = $workflow.id;
return [{
  json: {
    executionId,
    workflowId,
    workflowName: $workflow.name,
    mode: $execution.mode,
    startedAt: new Date().toISOString(),
    status: "success",
    data: { resultData: { runData: $execution.data?.resultData?.runData || {} } },
    workflow: $workflow  // Include for structural analysis
  }
}];

1. Configure the HTTP Request node:

URL: https://api.pisama.ai/api/v1/n8n/webhook
Method: POST
Headers:
  X-Pisama-API-Key: <your_api_key>
  X-Pisama-Signature: <hmac_signature>
  X-Pisama-Timestamp: <unix_timestamp>
  Content-Type: application/json

Webhook payload format:

{
  "executionId": "123",
  "workflowId": "abc",
  "workflowName": "My AI Workflow",
  "mode": "trigger",
  "startedAt": "2024-01-01T00:00:00Z",
  "finishedAt": "2024-01-01T00:00:05Z",
  "status": "success",
  "data": {
    "resultData": {
      "runData": {
        "OpenAI": [{"data": [...], "executionTime": 1500}],
        "Process": [{"data": [...], "executionTime": 50}]
      }
    }
  },
  "workflow": { ... }
}

Including the workflow field enables structural analysis (cycle detection, complexity, error handling, resource, timeout).

Security: Webhook requests are verified using HMAC-SHA256 signatures with replay protection:

• X-Pisama-Signature: HMAC signature of the payload
• X-Pisama-Timestamp: Unix timestamp (must be within 5 minutes)
• X-Pisama-Nonce: Unique nonce to prevent replay attacks

Method 2: API Polling¶

Pisama polls the n8n API for recent executions. No workflow modifications needed, but requires n8n API credentials.

# Set environment variables
export N8N_HOST=https://your-n8n-instance.com
export N8N_API_KEY=your_n8n_api_key

Sync historical executions:

curl -X POST http://localhost:8000/api/v1/n8n/sync \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Check sync status:

curl http://localhost:8000/api/v1/n8n/sync/status \
  -H "Authorization: Bearer $TOKEN"

Method 3: Workflow Discovery¶

Pisama can automatically discover workflows from a connected n8n instance:

curl -X POST http://localhost:8000/api/v1/n8n/discover \
  -H "Authorization: Bearer $TOKEN"

n8n-Specific Detectors¶

Pisama includes 6 detectors designed specifically for n8n workflows:

These detectors analyze workflow structure (JSON definition) rather than execution behavior.

API Endpoints¶

AI Node Detection¶

Pisama automatically identifies AI/LLM nodes in n8n workflows and extracts token usage data:

Recognized AI node types:

• n8n-nodes-base.openAi
• n8n-nodes-base.anthropic
• n8n-nodes-langchain.agent
• n8n-nodes-langchain.chainLlm
• @n8n/n8n-nodes-langchain.lmChatOpenAi
• @n8n/n8n-nodes-langchain.lmChatAnthropic

Real-Time Monitoring¶

Connect to the SSE stream for live updates:

curl -N http://localhost:8000/api/v1/n8n/stream \
  -H "Authorization: Bearer $TOKEN"

Events include:

• Workflow execution started/completed
• Failure detected during execution
• AI node token usage alerts

Environment Variables¶