KSeF E-Invoice Exception Handling n8n Webhooks + Gmail

KSeF e-Invoice Exception Handling for n8n: Webhooks + Gmail alerts

Automate KSeF e-invoice intake, validation, retry-safe status checks, and exception routing in n8n—using a token-protected webhook and Gmail to send controlled internal summaries and aged recovery alerts for unresolved cases.

What this workflow does

• Receives invoice data securely via a webhook that requires a KSEF_INTAKE_TOKEN (sent as x-ksef-token or through the synthetic fixture). Missing/incorrect tokens return 401.
• Validates before persistence by checking required fields, basic XML shape, NIP checksums, caller-provided VAT-whitelist status, and supplied approval records—then stores the exact JSON snapshot and a SHA-256 hash.
• Routes outcomes through lifecycle states so one manual execution can handle submission, recovery, or fixture intake. Before any bundled adapter runs, it re-reads lifecycle state and writes a fail-stop durable intent row.
• Uses local mock submission for deterministic runs, then appends lifecycle transitions, evidence, exceptions, and run summaries to four n8n Data Tables.
• Checks status before retrying by querying the local mock status adapter. If the result is UNKNOWN, ERROR, or non-authoritative, it keeps cases on hold without submitting.
• Retries only once and only after an authoritative NOT_FOUND.
• Notifies via Gmail after persistence checks succeed: it sends controlled internal intake summaries and aged-recovery alerts for related unresolved records.

Use cases

• Process incoming KSeF e-invoice payloads from your SaaS and ensure invalid requests fail fast with 401.
• Recover invoices after transient issues by querying status first, then retrying only when NOT_FOUND is authoritative.
• Maintain an exception queue with evidence and lifecycle audit trails, with Gmail updates for aged recoveries.

Technical details

• Nodes/logic used: webhook, if, code, switch, data table, gmail.
• Create and map: KSeF_Lifecycle, KSeF_Evidence_Log, KSeF_Exception_Queue, KSeF_Run_Summaries; re-select each table ID in every Data Table node.
• Webhook auth: configure KSEF_INTAKE_TOKEN and send it in x-ksef-token.