Most integration failures do not begin with a dramatic outage. They begin with a quiet question: did the records move, and what should we do if they did not?
When a website, CRM, payment platform, email system, or reporting database exchanges data, the first incident is rarely the best time to decide who owns the workflow, where to find the logs, or whether a retry is safe. An integration runbook turns those decisions into a shared operating guide before a sync failure becomes a guessing exercise.
This is not a document for developers alone. A useful runbook gives marketers, operations teams, analysts, and support staff enough context to recognize a problem, collect the right evidence, and escalate it without exposing sensitive data or creating duplicate work.
What an integration runbook should answer
A runbook is a short, practical guide for operating a known workflow. For an integration, it should answer five questions:
- What systems exchange data, and what business process depends on the exchange?
- What does a healthy run look like?
- How can someone tell whether a failure is temporary, partial, or permanent?
- What actions are safe for the first person who notices the problem?
- When should the issue move to an engineer, vendor, or system owner?
The answers should be specific enough to use during a real incident. “Check the integration” is not a step. “Compare the last successful run time with the source export timestamp, then record the run ID and rejected-record count” is a step.
Start with the business outcome, not the endpoint
Technical diagrams often begin with an API endpoint. Runbooks should begin with the reason the integration exists.
For example, a nonprofit may sync completed donation records from a payment platform into a CRM and then send eligible donors into an email audience. A failure can affect receipting, stewardship, campaign attribution, and suppression rules even when each individual platform remains online.
Write the business outcome in one sentence, then name the systems involved. Include the direction of travel, the expected schedule or trigger, and the record type. A compact entry might look like this:
Completed gifts move from the payment platform to the CRM every 15 minutes. New or changed CRM contacts then sync to the email platform for receipt and stewardship workflows.
This description gives a nontechnical reader a reason to care and gives a technical reader a boundary for investigation.
Document the normal path
Before describing failure handling, document what a successful record journey looks like. Use plain language and a small flow diagram if one is available:
- A source event is created or updated.
- The integration reads the record and maps source fields to destination fields.
- The destination accepts, transforms, or rejects the record.
- The integration records a result, timestamp, and identifier.
- A downstream workflow uses the updated record.
For each stage, record the fields that matter for reconciliation. These may include a source record ID, destination record ID, event type, created or updated time, sync status, attempt count, and error category. Avoid copying full names, email addresses, payment details, survey answers, or other sensitive values into the runbook. The guide should explain how to locate evidence without becoming a second database.
Define healthy signals and warning signals
People can respond quickly when “healthy” has a concrete definition. Depending on the workflow, healthy signals might include:
- The latest run completed within its expected interval.
- The number of records read is plausible compared with the source system.
- Accepted and rejected counts are present and explainable.
- Destination records contain the expected stable identifiers.
- Downstream events, such as an email enrollment or report refresh, occur within an agreed window.
Warning signals deserve the same precision. A growing queue, an unusual drop in source volume, a spike in validation errors, missing destination IDs, or a downstream report that has not refreshed can each indicate a different failure mode.
Use thresholds carefully. A fixed number may be useful for a small, predictable workflow, but percentage change or comparison with recent successful runs is often more meaningful. Document who reviews the signal and how often, rather than assuming an alert will always reach the right person.
Separate failure types
One of the most useful sections in a runbook is a small decision table that distinguishes failure types. The first action depends on the type of problem.
- Trigger failure: the scheduled job or webhook did not start.
- Transport failure: the request could not reach the source or destination.
- Authentication failure: credentials, tokens, or permissions prevented access.
- Validation failure: a record was received but did not meet required field or format rules.
- Mapping failure: the record arrived, but a field or identifier could not be translated correctly.
- Destination failure: the receiving system rejected or could not store the record.
- Partial success: some records completed while others failed.
- Downstream failure: the source and destination updated, but a later report, email, or workflow did not.
These labels help teams avoid treating every problem as “the API is down.” They also make support conversations more useful because an incident can be described in terms of evidence rather than suspicion.
Make the first response safe
A runbook should state what the first responder may do without engineering approval. Safe actions might include checking the last run, capturing a run ID, reviewing a redacted error summary, confirming whether the source record exists, and noting whether the issue affects one record or a wider batch.
It should also state what not to do. Do not repeatedly click a “run now” button when the workflow is not idempotent. Do not edit production records to make an error disappear. Do not paste a full export into a ticket or chat channel. Do not rotate credentials during an active incident unless the owner has confirmed that access is the problem.
When a retry is allowed, explain the conditions. A retry may be safe when the integration uses a stable idempotency key and records the destination result. It may be unsafe when the destination creates a new transaction each time or when the workflow has no way to tell whether a prior attempt completed.
Include evidence and escalation rules
Every escalation should carry the same minimum evidence. Define a small incident template that includes:
- Workflow name and environment.
- Approximate start time and the last known healthy run.
- Run ID, batch ID, or source and destination record IDs.
- Failure type and a short redacted error message.
- Record counts read, accepted, rejected, retried, and unresolved.
- Actions already taken and their results.
- Whether the issue is isolated, recurring, or expanding.
Then define escalation paths. A validation problem may go to the data owner. An authentication problem may need the integration owner or system administrator. A destination outage may require a vendor ticket. A privacy concern should have a clear security or compliance contact. Include business-hours and after-hours expectations so nobody has to infer urgency from the tone of a message.
Design for reconciliation, not just recovery
Recovery is not complete when a job turns green. The team still needs to know whether every expected record arrived exactly once, whether any records were skipped, and whether downstream actions happened.
Give the runbook a reconciliation procedure. It might compare source and destination counts for a defined time window, match stable IDs, review rejected records, and confirm downstream timestamps. For a donation workflow, reconciliation could include the source gift count, CRM gift count, total amount by day, and the number of records waiting for manual review. For a form workflow, it could compare submission IDs with CRM activity and notification logs.
Keep the comparison window explicit. “Check yesterday’s records” can be ambiguous across time zones and late-arriving events. Define the time zone, inclusion rules, and treatment of updates or cancellations.
Keep the runbook maintainable
A runbook becomes unreliable when it describes an old system. Assign an owner, a review cadence, and a change trigger. Review it after a platform change, field-mapping change, authentication change, incident, or vendor migration.
Link to the canonical dashboard, log view, field map, and vendor documentation, but do not scatter critical instructions across inaccessible personal notes. Use version history for the runbook itself, and record the date of the last test. A short guide that was exercised last month is more valuable than a long guide that no one has opened since launch.
A practical pre-launch test
Before an integration goes live, ask someone who did not build it to use the runbook with a controlled test record. Can they identify the source ID? Can they find the destination result? Can they tell a rejected record from a delayed record? Do the escalation contacts still work? Can they complete the process without seeing sensitive data they do not need?
Test at least one normal record, one validation failure, one temporary transport failure, one duplicate or replay scenario, and one partial batch. Record the gaps. Those gaps are not paperwork problems; they are signals that the system or its operating model needs more clarity.
Make the first incident less improvisational
An integration runbook will not prevent every failure. It can prevent the avoidable confusion that follows one. By documenting the business outcome, normal data path, healthy signals, failure types, safe actions, evidence, escalation rules, and reconciliation steps, teams can respond with facts and protect the integrity of the systems connected to the workflow.
DigitalWerks helps organizations map, build, monitor, and validate the integrations that connect websites, forms, CRMs, payment platforms, email systems, and reporting tools. If your team has a sync that depends on tribal knowledge, we can help turn it into a workflow people can operate with confidence. Talk with DigitalWerks about reviewing your integration runbook.