n8n Integration Guide

Turn an "agent execution complete" webhook into a verifiable AgnCred work receipt with an importable n8n workflow. This is a pointer guide — the authoritative documentation, sample payloads, and troubleshooting table live in examples/n8n/README.md.

The workflow uses built-in n8n nodes only (Webhook, Code, HTTP Request, Wait, IF). There is no custom community node to install.

Import in four steps

Set environment variables for the n8n process (shell, systemd, or docker -e):
```
export AGNCRED_API_URL="https://your-agncred-host"   # no trailing slash
export AGNCRED_API_KEY="agk_..."                     # agent credential with receipts:create + receipts:read
```
n8n must allow env access in expressions (do not set N8N_BLOCK_ENV_ACCESS_IN_NODE=true). On n8n Cloud, $env is unavailable — use a Header Auth credential instead.
Import examples/n8n/agncred-submit-receipt.workflow.json (Workflows → Import from File). The Webhook node ships with a sample payload pinned, so Execute workflow runs the full chain without an external caller; delete the pin for production.
Activate the workflow and point your agent system at the production webhook URL (POST /webhook/agent-execution-complete).
Persist the receipt: the Store receipt id node exposes receipt_id and verification_url — add a database/sheet node after it so receipts are findable independently of n8n's execution history.

Restricted-field stripping

Receipts are privacy-safe by construction: the mapping Code node uses an allowlist, never a blocklist. Metrics survive only if scalar, non-restricted (prompt, source_code, customer*, credential, api_key, secret, token, password, raw_output are dropped), and on the explicit METRIC_ALLOWLIST or plain safe identifiers. Free-text claims and summaries are dropped entirely if they look like they embed secrets. The execution-log URL travels as an evidence descriptor with confidentiality: "private_reference" — stored erasably, only its hash enters the immutable payload. Extend METRIC_ALLOWLIST for your workflows instead of loosening the checks.

Idempotency and polling

Idempotency: the workflow sends Idempotency-Key: n8n-<workflow id>-<execution id>, so HTTP retries replay (200 replayed: true) instead of duplicating. If your source system may redeliver the same event as a new n8n execution, key on the source execution ID instead (comment in the Map node shows how).
Polling: AgnCred has no outbound webhooks. The workflow polls GET /api/v1/agent/receipts/{id} every 30 seconds, at most 10 times, ending on accepted/rejected/disputed or with "still_pending" when the budget runs out. Human review usually takes hours or days — for production widen the Wait interval and MAX_POLLS, or re-poll stored receipt IDs from a scheduled workflow.