HubSpot Integration QA Checklist and Test Matrix

An outside builder’s integration is ready for a consultancy to review when the delivery pod can answer three questions from evidence: what was supposed to happen, what actually happened in each important case, and what an operator should do when the next case fails. A working demo is useful, but it rarely shows duplicate delivery, missing identifiers, rejected values, or partial completion. The handoff should make those conditions inspectable without relying on the builder’s memory.

This article is about the evidence package for one external API or sync component, not a checklist for an entire HubSpot implementation. The component-scope brief defines the assigned boundary. The QA pack demonstrates that the build stays inside it and gives the pod enough context to accept or reject it.

Download the integration QA acceptance matrix

Download the editable CRM integration QA matrix (CSV). It contains seven synthetic scenarios, with space for expected behavior, actual results, a verdict, an evidence reference, and the responsible owner. Every row starts as not tested. These are proposed test cases, not results from a client implementation.

Scenario	What the reviewer needs to see
Normal update	The approved contact changes once, with unrelated fields unchanged.
Duplicate delivery	Replaying one event does not create a second task or notification.
Missing match	An unknown identifier creates an owned exception, without a guessed association.
Invalid value	A rejected value remains visible for correction.
Timeout after write	The operator inspects the destination before deciding whether to retry.
Permission denied	Missing access produces a clear blocked state.
Resume after pause	The agreed backlog resumes without lost or repeated work.

Before testing, replace the proposed outcomes with the client's approved rules. Use a suitable test environment and synthetic records. HubSpot describes its developer test environment in the developer platform onboarding guide. Confirm which features and permissions are available in your account rather than assuming that test and production behave identically.

Keep record references in the matrix and sensitive payloads in the client's approved evidence store. A reviewer should be able to trace one row from requirement to input, destination state, verdict, and recovery owner. When a test is blocked, preserve that verdict instead of treating a missing result as a pass.

Assign the acceptance decisions

The solution architect or technical lead should approve the intended behavior. The implementation manager should know which client decision is still open. The builder should convert the agreed behavior into tests and bring back results. These can be three people or fewer, but the decision rights should be written down. A builder cannot prove correctness against an unwritten rule.

Use one line per case. Include the source event or batch reference, expected HubSpot object and record, allowed property changes, forbidden side effects, expected exception route, and person who can resolve an open business question. A useful example is a fictional booking system sending a confirmed booking to a known contact. The expected result names the contact’s approved cross-system ID and the single status update. It does not merely say “sync succeeds.”

Write negative cases as carefully as positive ones. A booking with no approved match should not be attached to the first similar email address. A repeated source event should not create a second task. An invalid option value should be visible for correction without being silently mapped to “other.” The client may choose different policies, but the test must reflect its chosen policy.

Keep a compact evidence index

The reviewer should be able to open one index and find the relevant record, log, and decision. A row can use these columns:

Field	Evidence to retain
Scenario ID	A stable name such as unknown-contact or timeout-after-write.
Requirement	Link to the approved rule or scope decision.
Test input	Synthetic or client-approved record reference, not an unrestricted payload copy.
Expected result	Object, record, property, association, side effect, and exception state as applicable.
Actual result	Observed HubSpot record ID, source reference, and operator-visible state.
Verdict	Pass, fail, blocked, or not tested, with a reason.
Evidence location	Test log, screenshot, or query output the pod can access under client policy.
Owner	Who fixes a failure or decides an ambiguous result.

Use the same scenario ID in the test notes and integration logs. If the connector provides its own execution ID, record the relationship to the source event and destination record. This is especially useful when a request times out after the destination may already have written data. Avoid logging tokens, complete personal records, or a second uncontrolled copy of client data.

Show the records, not only the API response

For a normal case, inspect the destination record and its associations. Confirm that the intended property changed and that unrelated properties, owner, lifecycle stage, and communication preferences did not change. For a new record, verify that the client-approved create rule was met. For an existing record, verify the lookup used the approved identifier and did not guess from a weak match.

For a repeated event, compare the record, tasks, notifications, and any outbound activity before and after the replay. A 200 response is insufficient if the same side effect occurred twice. For a temporary failure, show the waiting state and the bounded retry result. For an invalid value or denied permission, show a blocked state with an actionable reason. The safe retry design explains how to distinguish a confirmed failure from an ambiguous timeout.

Test with the permissions the integration will actually have, and record the environment. An administrator account can make an otherwise broken integration appear healthy. If a test environment differs from production in fields, scopes, workflows, or external-system behavior, list those differences and the production checks required at release. Confirm endpoint and error behavior against HubSpot’s current API reference and the external system’s documentation rather than assuming behavior from an older project.

Make partial completion visible

Multi-step components can be half done. Imagine a contact update succeeds, then task creation fails. The QA pack should show the completed contact write, the failed task step, and what the next attempt will do. Replaying the entire workflow without checking completed side effects can create a second task or overwrite a later update. An operator needs to know whether to resume, correct input, or stop for review.

Test one failure after each consequential boundary: before sending, after destination acceptance but before local success is stored, and during a later action. The exact fault-injection method depends on the integration tool. If the tool cannot reproduce a boundary safely, mark it not tested and explain how early live events will be observed. Do not convert that limitation into a pass because the demo looked clean.

Evidence should also show the exception route. A log entry that only an engineer can find at midnight is not an operator procedure. The review item should identify the source reference, the last confirmed step, the likely cause, and the safe next action. The implementation manager should know who receives it and who can authorize a replay that might affect a customer.

Give the pod a release and recovery note

The evidence pack is complete only when the pod can operate the component after the builder leaves. Include the code or workflow location, version, environment, configuration dependencies, credential owner, approved property map, test index, known limitations, monitoring view, and pause procedure. The runbook should say which events can be retried automatically, which need a lookup, and which require a client decision. It should also explain that pausing new work does not reverse earlier writes or messages.

At review, ask a pod member who did not build the component to trace one successful event and one failed event using the notes alone. If they cannot find the source, destination, or next owner, improve the package before client sign-off. The broader HubSpot implementation handoff checklist covers the client-facing workflow and operating notes beyond this single component.

After release, sample real transactions within the agreed observation window. Compare source events with destination changes and exception items. A low error count is meaningful only if events are arriving and the monitor is working. Classify new issues as build defects, data problems, access changes, or changed business rules before editing production behavior. Keep the pod’s acceptance record connected to the version that was actually released.

Syncraft’s Sheelaa integration case study shows API and workflow work across messaging channels, a database, a dashboard, and a Sheets sync. It is relevant engineering proof, not a HubSpot delivery claim. For a defined client component, Syncraft describes its CRM and RevOps implementation support, with one active workstream and a complimentary sample-data workflow design before live-account work is scoped.