n8n Integration¶

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

Pisama is not affiliated with or endorsed by n8n.

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: Community node (recommended)¶

The n8n-nodes-pisama community node (npm, v0.3.0, MIT) sends execution data to Pisama after each run, with request signing handled for you.

Requirements: a self-hosted n8n instance. Community nodes cannot be installed on n8n Cloud; if you are on n8n Cloud, use the manual wiring appendix instead. The node is built and tested against n8n-workflow ^1.70.

Setup:

1. Install the community node. In n8n, open Settings, then Community Nodes, and install n8n-nodes-pisama.

2. Create a Pisama API key at pisama.ai/settings/api-keys.

3. Register the workflow in Pisama. Use the /n8n page in the app, or the API:

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"}'

Registration mints the workflow's webhook secret (the response includes webhook_secret and webhook_url; re-registering the same workflow returns the existing secret). Ingestion is fail-closed: only signed traffic from registered workflows is accepted, and executions for unregistered workflows are rejected with 403.

1. Add the Pisama node as the last step of the workflow and create the Pisama API credential. The credential has three required fields:

Optional but recommended: fill in n8nApiUrl and n8nApiKey (your n8n instance's own API credentials). With them, Pisama pulls the authoritative execution and the full workflow JSON, which unlocks full structural analysis. Without them, structural detectors run degraded because node types and connections are unknown.

1. Run the workflow. Executions appear in the Pisama dashboard with any detections.

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¶

Structural detectors 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¶

Appendix: manual wiring¶

Manual wiring works on n8n Cloud (where community nodes cannot be installed) and on instances where you cannot install community nodes. You construct and sign the webhook request yourself instead of using the Pisama node.

Setup:

1. Register the workflow in Pisama first (this mints the webhook secret; executions for unregistered workflows are rejected with 403):

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 to POST to https://api.pisama.ai/api/v1/n8n/webhook with these headers:

Webhook payload format:

{
  "executionId": "1042",
  "workflowId": "abc",
  "workflowName": "My AI Workflow",
  "mode": "trigger",
  "startedAt": "2026-01-01T00:00:00.000Z",
  "finishedAt": "2026-01-01T00:00:05.000Z",
  "status": "success",
  "data": {
    "resultData": {
      "runData": {
        "OpenAI": [
          {
            "data": {"main": [[{"json": {"text": "Draft reply: thanks for reaching out."}}]]},
            "executionTime": 1500,
            "startTime": 1704067200000
          }
        ],
        "Process": [
          {
            "data": {"main": [[{"json": {"text": "reply saved"}}]]},
            "executionTime": 50,
            "startTime": 1704067201500
          }
        ]
      }
    }
  },
  "workflow": {"id": "abc", "name": "My AI Workflow", "nodes": [], "connections": {}}
}

executionId and workflowId are required (camelCase). data.resultData.runData maps each node name to a list of run objects. Including the workflow field (the full n8n workflow JSON) enables structural analysis (cycle detection, complexity, error handling, resource, timeout).

Security: Webhook requests are verified using HMAC-SHA256 signatures with replay protection. Requests without a valid signature from a registered workflow are rejected with 403: only signed, registered traffic is accepted.