VamimiOpen VamimiAI

Automation documentation

How to Document an n8n Workflow for a Client

A handover (or handoff) checklist for n8n freelancers and agencies: what to write down, what to draw, and how to show a client what a failure does.

By VamimiAI team · · 5 min read

To document an n8n workflow for a client, give them four things in plain words: what starts it, what it does step by step, what happens when a step fails, and what they must keep working (logins, sheets, webhook addresses). A diagram that shows every path, including the failure paths, does most of that work; a one-page handover document does the rest.

This guide is a checklist you can follow for every workflow you hand over (some call it the handoff), whether you build for one client or fifty.

Why the workflow file is not documentation

The exported .json file is a backup, not an explanation. A client who opens it sees node parameters and IDs. A screenshot of the canvas is better, but it shows node types (HTTP Request, Set, If) rather than what the business gets, and it never shows what happens when a node fails, because n8n draws only the paths you connected.

That last part is what costs you later. Most nodes that call an outside service stop the whole run when that service is down, rate-limits you or loses its login. Unless the workflow has an error workflow set, nobody is told. The client finds out when a customer complains.

The handover checklist

Work through these in order. Each one answers a question your client will otherwise ask you by email.

  1. What starts it. The trigger in client words: "a new row in the Leads sheet", "every weekday at 8:00", "a payment in Stripe". If it is a webhook, say which system calls it.
  2. What it does. One line per step, named the way the client knows the apps: "Adds the lead to HubSpot", not "HTTP Request 3".
  3. What happens when each step fails. For every step that calls another service: does it retry, does it continue, or does the run stop? Who is told?
  4. What it depends on. The accounts and credentials by name (never the values), the sheets and their column names, the webhook URLs, any limits on the plan it runs on.
  5. How to look after it. Where failed runs show up (the Executions list in n8n), what is safe to change, and who to call.
  6. What was left out. Anything you agreed not to build. It saves an argument about scope later.

What the exported JSON contains

An n8n export carries the names and IDs of the credentials the workflow uses, and anything typed straight into a node, keys included. Before the file goes to a client, or anywhere else, check that every secret lives in a stored credential rather than in a node. Give the client the JSON as a backup they own, with the documentation beside it, not instead of it. If the documentation lives in a README or wiki, the diagram can go there as Mermaid text or a draw.io file.

Draw it, including the failure paths

A diagram answers the first three questions at a glance, but only if it shows the failure paths. Draw the decisions with labelled exits (Yes / No, the names of Switch outputs), and for every step that can fail, a dashed line to what really happens next: a retry, an alert, or a red end that says the run stops.

You can draw this by hand, or import the workflow into VamimiAI's n8n workflow diagram. It reads the exported file as it is, with no AI guesswork: If and Switch branches are labelled, error outputs are drawn dashed, and each node that calls an outside service with no retry and no error path leads to a red end saying the run stops and whether anyone is told.

Check it before you hand it over

Documenting a workflow is the moment you notice what will break. Before the handover, look for:

  • Webhooks without authentication. Anyone who finds the address can start the workflow.
  • Keys typed into a node instead of stored as a credential. They travel with every export of the workflow.
  • If exits that lead nowhere, and nodes nothing reaches.
  • No error workflow in the workflow settings, so failures are silent.
  • Default node names like "HTTP Request1", which make the execution log unreadable for the next person.

VamimiAI runs these checks on import and lists them most serious first, with the fix for each. A secret is reported by the name of its field only; its value is never shown.

Write the handover document

Put it all on one page the client can keep: the diagram first, then a table of what each step does and what happens if it fails, the accounts it needs, and short notes on looking after it. Add your name and contact details so they know who to call.

The automation handover document in VamimiAI builds exactly this page from an imported or described workflow. It is put together in your browser, and you can print it, save it as PDF or download it as a web page. The list of problems found is left out unless you choose to include it.

For the failure paths specifically, the n8n error handling guide goes through each option n8n gives you and when to use it.

Questions

What should an n8n handover document include?

The trigger, each step in plain words, what happens when each step fails, the accounts and sheets it depends on, where failed runs show up, and who to contact. A diagram that shows every path, including failures, should come first.

Should I give the client the workflow JSON?

Yes, as a backup they own, but not as the documentation. Keep credentials out of it: anything typed directly into a node travels with the export, while stored credentials do not.

How do I show a client what happens when a step fails?

Draw a dashed line from every step that calls an outside service to what really happens next: a retry, an alert, an error output or a red end where the run stops. Importing the workflow into VamimiAI draws those paths from the file.

Tools for this