Skip to main content

What should be in an integration runbook, and what documentation should I demand from my developer?

A runbook should let someone who has never seen your integration keep it running, fix it and roll it back. Ask for six things: who owns the credentials, error handling, logging, re-authentication steps, a field mapping document and a rollback procedure. On a two-system integration that takes about 4–8 hours of engineering to write.

Why the runbook matters more than the code

Most automations fail the same way. They run fine for months, a token expires or a field gets renamed, and the one person who understood them has left, changed jobs or stopped answering email. That is key-person risk, and a runbook is your protection against it.

Code you own but cannot operate is not much better than code you do not own. The test is simple: could a competent developer who has never met your original builder restore a broken sync within a day, using only what is written down? If not, the handover is not finished.

In our own engagements, writing the runbook takes about 4–8 hours on a typical two-system integration, which is roughly $340–$680 at our $85 hourly rate. That is a small part of a $1,500–$6,000 build, and we treat it as part of the build rather than an add-on.

The six-part checklist

Ask for each of these in writing before you approve final payment. The right-hand column is how to check you actually got it.

Item What it must contain How to check it
Credentials ownership Every API key, OAuth app and service account, which account it lives under, who can rotate it Each credential is under a company account or vault, not the developer’s personal login
Error handling What happens on each failure type: retry, queue, alert or stop Ask what happens if the target system is down for an hour
Logging Where logs live, how long they are kept, what one failed record looks like Ask them to show you the log entry for a single failed sync
Re-auth steps Step-by-step reconnection for each system, with the screens and permissions needed A non-developer on your team can follow it
Field mapping doc Every source field, target field, transformation and default value Pick three fields and trace them end to end
Rollback How to pause the integration, revert a deploy and undo bad writes Ask how long a rollback takes and who can do it

Credentials ownership

This is the item that causes the most damage when it is missing. If the HubSpot private app or the Stripe restricted key was created under a contractor’s login, you cannot rotate it without them. Demand that every credential sits in an account your company controls, stored in a password manager or secrets store, with a written list of what each one can access.

Error handling and logging

The runbook should name each failure the integration expects and what it does about it. Look for answers to rate limits, timeouts, duplicate records, partial failures where one write succeeds and the next does not, and data that arrives before the record it belongs to. Logs should say which record failed and why, in plain enough terms that you can search for a customer name.

Field mapping and rollback

The mapping document is what saves you when someone adds a custom field upstream or changes a picklist value. Rollback is what saves you when a bad deploy writes 400 wrong invoices. Both should be short, current and stored in your repository or shared drive, not in an email thread.

A worked example: what one runbook entry looks like

Take a common stack: HubSpot closed-won → QuickBooks Online customer and draft invoice → Stripe payment webhook marks the deal paid. Here is what the runbook should cover for that flow.

  • Trigger: deal stage changes to closedwon. The integration checks for an existing QuickBooks customer by email before creating one, so a repeat buyer does not become a duplicate.
  • Stored IDs: the QuickBooks customer ID and invoice ID are written back to custom HubSpot deal properties, which is how the Stripe webhook later finds the right deal.
  • Failure: if QuickBooks rejects the invoice, the deal gets a sync_status of failed, the error is logged with the deal ID, and an email goes to the finance lead.
  • Out-of-order data: if a Stripe payment arrives before the invoice exists, the event is held and retried for 24 hours instead of dropped.
  • Re-auth: QuickBooks Online connections expire on a schedule set by Intuit. The runbook lists the reconnect steps, the admin role required and the symptom you will see when it lapses.
  • Rollback: one setting pauses the sync; a script lists every invoice created in a given window so bad ones can be voided.

That is roughly a page and a half. It is enough for a new engineer, or your controller, to understand what the system does and what to do on a bad morning.

We wrote ours this way for a Stripe-to-Salesforce and Google Sheets finance sync that has now run for two years with minimal maintenance. The documentation is a large part of why maintenance stays minimal: nobody has to rediscover how it works.

Other documentation worth asking for

  • Repository access: the code in a GitHub or similar account your company owns, with deploy instructions in the README.
  • Hosting inventory: where it runs, who pays for it, and what it costs each month.
  • Dependency list: which vendor APIs and versions it relies on, so you know what to check when a vendor announces a change.
  • Monitoring: what alerts exist, who receives them, and what silence means.
  • Known limits: volumes it was tested at, and what it does not handle yet.

For no-code builds in Zapier, Make or n8n, the same list applies with smaller answers. The workflows should live in a company-owned workspace, connections should use company accounts, and the field mapping should be written down rather than only visible inside each step.

When to insist, and when not to bother

Insist on the full checklist when the integration touches money, customer records or anything your team would notice within a day if it stopped. Insist harder if one contractor built it and nobody inside your company has looked at the code.

A single Zapier zap that copies form entries into a spreadsheet does not need a formal runbook. A paragraph saying what it does, which account owns it and how to reconnect it is enough, and you can write that yourself in 20 minutes.

If you already have an integration with no documentation, you do not necessarily need to rebuild it. Often the right move is to pay for a few hours of reverse engineering to produce the six items above, then decide whether the code is worth keeping.

Frequently asked questions

What is an integration runbook?
An integration runbook is a written operating guide for an automation between business systems. It covers who owns the credentials, how errors are handled, where logs live, how to re-authenticate, how fields are mapped and how to roll back. Its job is to let someone other than the original builder keep the integration running.

How much should integration documentation cost?
At Smplfy, a runbook for a typical two-system integration takes about 4–8 hours, roughly $340–$680 at our $85 hourly rate. We include it in the build price. If a developer quotes documentation as a large separate line item, ask what you are getting beyond the six core items.

Who should own the API keys for my integrations?
Your company should. Every API key, OAuth app and service account should be created under a company-controlled account and stored in a password manager or secrets store. If a contractor’s personal login holds a credential, you cannot rotate or revoke it without them.

Do Zapier or Make automations need a runbook?
Simple ones need a short note: what the automation does, which account owns it and how to reconnect it. Multi-step scenarios that touch invoices, payments or customer records deserve the full checklist, including a written field mapping, because the logic is spread across many steps that are hard to review.

What if my developer left and there is no documentation?
Do not rush into a rebuild. A few hours of review can usually reconstruct the credentials list, field mapping and failure points from the code and logs. Once those are written down, you can decide whether the existing integration is worth keeping or should be replaced.

Related answers

Want your integrations documented before something breaks?

We offer a free 20-minute call or a short written scope. Have ready which systems are connected, roughly how many records move each month, and what documentation exists today. Start a conversation.