Dify Integration¶

Pisama integrates with Dify to monitor AI application workflows and detect failure modes in Dify-built agents.

Setup¶

1. Get a Bearer Token¶

curl -X POST https://api.pisama.ai/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "pisama_your_api_key_here"}'
export TOKEN="<access_token>"

2. Register a Dify Instance¶

curl -X POST https://api.pisama.ai/api/v1/dify/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-dify",
    "base_url": "http://localhost:80",
    "api_key": "your_dify_api_key"
  }'

3. Register Apps for Monitoring¶

curl -X POST https://api.pisama.ai/api/v1/dify/apps \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "<instance_id>",
    "app_id": "my-chatbot-app",
    "app_name": "Customer Support Bot",
    "app_type": "workflow"
  }'

The response includes a webhook_secret for HMAC signing.

4. Configure Webhook¶

Webhook requests require HMAC-SHA256 signing (same as OpenClaw and n8n):

URL: https://api.pisama.ai/api/v1/dify/webhook
Method: POST
Headers:
  X-Pisama-API-Key: <your_api_key>
  X-Pisama-Signature: sha256=<hmac_signature>
  X-Pisama-Timestamp: <unix_timestamp>

Payload:

{
  "workflow_run_id": "run-001",
  "app_id": "my-chatbot-app",
  "app_name": "My App",
  "app_type": "workflow",
  "started_at": "2026-04-06T20:00:00Z",
  "finished_at": "2026-04-06T20:00:05Z",
  "status": "succeeded",
  "total_tokens": 150,
  "total_steps": 3,
  "nodes": [
    {"node_id": "1", "node_type": "llm", "title": "Classify", "status": "succeeded",
     "inputs": {}, "outputs": {"text": "positive"}, "elapsed_time": 1.2}
  ]
}

Detection Capabilities¶

Dify-Specific Detectors¶

Detector	Key	What It Detects
Iteration Escape	`dify_iteration_escape`	Runaway iteration/loop nodes exceeding safe limits
RAG Poisoning	`dify_rag_poisoning`	Poisoned knowledge retrieval documents
Model Fallback	`dify_model_fallback`	Silent model downgrade without logging
Variable Leak	`dify_variable_leak`	Sensitive data leaking across nodes
Classifier Drift	`dify_classifier_drift`	Question classifier miscategorization
Tool Schema Mismatch	`dify_tool_schema_mismatch`	Tool input/output schema violations

General Detectors (also apply)¶

Hallucination: LLM nodes generating unsupported claims
Loop detection: Workflow loops and retry storms
Context overflow: Token accumulation across workflow nodes
Task derailment: Agents going off-topic
State corruption: Data transformation errors between nodes
Cost tracking: Token usage and cost per workflow execution

API Endpoints¶

Method	Path	Description
`POST`	`/api/v1/dify/webhook`	Receive workflow execution webhook
`POST`	`/api/v1/dify/instances`	Register a Dify instance
`GET`	`/api/v1/dify/instances`	List registered instances
`POST`	`/api/v1/dify/apps`	Register an app for monitoring
`GET`	`/api/v1/dify/apps`	List registered apps
`GET`	`/api/v1/dify/stream`	SSE endpoint for real-time updates

Real-Time Monitoring¶

Connect to the SSE stream for live Dify execution updates:

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