What Goes in an Automation Handoff Document for a Client

What goes in an automation handoff document for a client?

Four things that a normal runbook leaves out. Who owns each account, what has to be reauthorised when ownership moves, what the automation deliberately does not do, and how the client verifies it is still working next month without calling you. Everything else is documentation, not handoff.

The distinction matters because teams conflate them. A runbook tells the people operating a system how to operate it. A handoff document assumes the author is leaving and the reader has never seen the inside of this thing. Those are different documents with different failure modes, and writing one when you needed the other is how clients end up with an automation nobody can touch.

I build automations for clients on Airtable, Whalesync, HubSpot, and Zapier, and the handoffs that went badly all failed in the same place, which is account ownership rather than logic. Nobody misunderstood what the automation was for. They lost access to the thing that ran it.

Why does ownership transfer break automations?

Because connections are authorised to a person, not to a workflow. When the underlying account changes hands, the authorisation that let your automation reach into that account becomes invalid, and the automation stops or errors even though nothing about its configuration changed.

Whalesync documents exactly this case for Webflow. If you transfer your Webflow site from one Webflow account to another, it says you can still continue to use your Whalesync sync, but it requires a few steps. You will first notice a Webflow sync issue, then go to Sync Settings, click Reauthorize on Webflow, and finally click retry syncing on the Issues page.

That is a completely reasonable process and it is invisible to a client who does not know it exists. Picture the sequence without the documentation. The site transfers, the sync silently stops, somebody notices two weeks later that the website is stale, and the person who built it has moved on. A single paragraph in a handoff document turns a two week outage into a five minute fix, and that paragraph is the highest value thing in the whole document.

What does publishing behaviour mean for handoff testing?

It means a handoff test can pass on data that never existed in the real system. Zapier documents that a published Zap will only process new data created after it is published. If you demonstrate the automation to a client using records that predate that moment, you have demonstrated nothing about production behaviour.

This bites at handoff specifically because handoffs happen at the end, when everyone wants to see it work one last time. The natural instinct is to point at an existing record and say watch this. With that publish rule in place, the honest test is to create something new after publication and follow it all the way through to its destination.

Write that instruction into the document rather than performing it once. The client will need to re-run this test after every change they make for the rest of the automation's life, and a described test they can repeat is worth more than a demo they watched you do.

Why is test data not proof that it works?

Because the platform tells you so. Zapier documents that test records are sample data used while building and may differ from the data your Zap receives during live runs. A workflow that passes every test step can still fail on the first real record, and the difference will be in fields that the sample happened not to include.

I have come to treat a green test as evidence that the wiring is correct and nothing more. The wiring being correct is genuinely useful information. It is just a much smaller claim than it feels like when every step shows a tick, and handoff is exactly the moment when people over-read those ticks.

So the handoff document should distinguish between two states clearly. Tested means the steps connect. Verified means a real record created in production travelled end to end and produced the correct result, observed by a named person on a date. Write the date and the name down. That single line is what a client can point at in six months when something looks wrong and they need to know whether it ever worked.

What do you document about credentials without writing them down?

The map, never the keys. Document which account each connection uses, which person or shared mailbox owns that account, where the credential is stored, who can rotate it, and what breaks when it is rotated. That is everything a client needs and none of it is a secret.

The item people forget is the rotation consequence. Every credential will eventually be rotated, usually by somebody in IT doing routine hygiene who has no idea an automation depends on it. If the document lists which automations depend on each credential, that person can check before rotating. If it does not, you get an outage with no obvious cause, which is the most expensive kind.

I also push hard for shared or service accounts rather than personal ones wherever the platform allows. An automation authorised through an individual's account has a countdown timer on it set to that person's last day. This is unglamorous advice that nobody takes seriously until the first time it happens, and then they take it very seriously forever.

How do you document what the automation does not do?

Explicitly, in its own section, in plain language. List the cases the automation ignores, the conditions under which it stops rather than continues, and the things a reasonable person might assume it handles but it does not. This section prevents more incidents than the section describing what it does.

The reason is that clients form a mental model from the demo, and that model is always more capable than the real thing. They saw a lead flow into the CRM, so they assume all leads flow into the CRM, including the ones from the form you were never told about. The gap between the assumed system and the actual one is where trust gets lost.

Being specific here also protects the client from themselves. If the document states that the automation does not deduplicate, does not backfill historical records, and does nothing when a required field is empty, then somebody planning a bulk import knows to ask a question first. I wrote about the operating side of this in the automation runbook to write before you ship, which is the document this one hands over to.

What does a handoff need that a diagram does not?

A failure section written for someone with no context. Diagrams show the happy path beautifully and say nothing about what a person should do at nine on a Monday when the thing has stopped. That is the only moment the document will ever really be read, and it should be written for that moment.

What I include is where errors appear, what the common ones look like in plain words, which are safe to retry, which mean data may have been partly written, and who to contact when it is none of the above. Naming where to look is more than half the value, because the first thing an unfamiliar person needs is a place to point their eyes.

I also include a deliberate section on the failure modes specific to the stack rather than to this build. If the automation syncs data between systems, the silent failure patterns are worth spelling out, since they are quiet by design. I went through a set of those in Airtable to Webflow sync failure modes, and a handoff document should carry the relevant ones rather than link to them.

How do you know the handoff actually worked?

Make the client drive while you watch. The test is not whether they understood your walkthrough, it is whether they can complete a defined task without you touching anything. Pick a real task, hand over the keyboard, and stay quiet.

The task I use is deliberately unglamorous. Change one mapped field, publish, create a real record, and confirm it arrives correctly at the other end. If they can do that unaided, they can maintain the automation. If they cannot, the document has a gap and you have just found exactly where it is, at the only point in the project when fixing it is still cheap.

Watching in silence is the hard part and it is the whole method. The moment you reach over to help, you have converted a test into another demonstration, and you will leave believing the handoff succeeded. I hold the same line on onboarding generally, which I described in my three hour contractor onboarding.

What should you do next?

Take one automation you currently maintain for someone else and write its ownership map. Every connection, the account behind it, the person behind the account, and what reauthorisation each one needs if that account moves. Half an hour, and it will surface at least one dependency on an individual that should not exist.

Then write the does not do section before anything else. It is the fastest to produce because you already know it, it is the part clients most need, and it will change how you describe the automation in every conversation afterwards.

If you are inheriting an automation rather than handing one over, run the same exercise in reverse and treat every blank you cannot fill as an open risk. And if you would rather have someone go through an existing automation with you and document it properly before the person who built it disappears, reach out and let's chat.