When an integration stops behaving as expected, the first delay can be deciding who owns the problem. The CRM administrator sees the missing update. A developer sees an error. The business team sees a customer process that no longer works.
We recommend writing the response plan before that conversation becomes urgent. A useful runbook connects the technical symptom to a business impact, an authorized responder and a test for recovery.
TLDR: Document what the integration does, who owns each component, how to recognize a failure, what evidence to collect, which actions are authorized and how to verify recovery. Treat retries and replay as controlled changes. Restoring API traffic is only part of the check if business records still need reconciliation.
Describe the source, destination, included objects and fields, update direction and authoritative system for each important value. Identify the schedule or event that triggers the transfer and the expected exception handling.
Add the business process affected by a failure. “Company sync is delayed” is less useful to an incident owner than “the account team cannot see the approved account status needed for its next action.” Keep the technical description, but connect it to a decision someone can make.
Use our overview of HubSpot integrations as inventory context if needed. The runbook must describe the actual connection and configuration your team uses.
Identify the business owner, the HubSpot administrator, the integration maintainer and the owner of the connected system. Record how each role can be reached and who covers an absence. Avoid assigning all responsibility to the person who first notices the symptom.
Specify who may inspect logs, change configuration, pause processing, rotate credentials or authorize replay. Access and permission to act are separate questions. An incident should not become an excuse to make a consequential change without the required approval.
If a provider is involved, retain the support route and the evidence it needs. Do not put credentials or secret values in the runbook.
HubSpot documents a 403 response when authentication lacks the permissions required for the requested endpoint, and a 429 response when an account or app exceeds an API rate limit. HubSpot's error-handling guide is the primary reference for those responses.
Those codes should guide investigation, not trigger an automatic permission expansion or an endless retry loop.
| Failure class | Evidence to collect | Decision to make |
|---|---|---|
| Authentication or permission | Endpoint, status, sanitized error and recent authorized changes. | Whether the approved access design still matches the operation. |
| Capacity or rate limit | Request pattern, affected operation and applicable limit documentation. | Whether to reduce, queue or reschedule traffic within the approved design. |
| Data or mapping | Affected identifiers, expected values and sanitized validation error. | Whether the source, mapping or business rule needs correction. |
| Transport or service interruption | Timing, affected components and current service evidence. | Whether to wait, contain the impact or escalate to the component owner. |
HubSpot publishes limits that vary by app, account and API context. Its usage guidelines should be checked for the actual endpoint and authentication model. Do not copy a single limit into every runbook.
Capture the time, affected operation, source and destination identifiers, observed status and a redacted error message. Record the last known successful operation and any approved changes that preceded the issue.
Avoid copying access tokens, authorization headers or complete customer payloads into a general work-management ticket. Define the minimum evidence needed and use the organization's approved location for anything sensitive.
The runbook should tell a responder how to preserve useful evidence before attempting a change. It should also identify when the available evidence is insufficient and the maintainer needs to investigate further.
Hypothetical example: A connection begins returning rate-limit errors while processing an approved backlog. The team confirms the affected operation and asks the authorized maintainer to adjust the request pattern. It does not repeatedly launch the same backlog without checking what already succeeded.
After the correction, the maintainer identifies the failed or unconfirmed items and proposes a bounded replay. Before approval, the team checks whether repeating an operation could create duplicate records, repeat a communication or overwrite a newer value.
This example illustrates the decision sequence. It does not prescribe a retry interval or claim that a particular API operation is safe to repeat. The actual behavior needs to be verified for the endpoint and integration implementation.
For broader troubleshooting context, review common HubSpot issues. Keep any platform-specific diagnostic procedure attached to the runbook rather than burying it in a general task description.
The recovery test should cover the original failure and any data left incomplete by the interruption. Check representative successful and exceptional cases, then reconcile the affected population according to the integration's purpose.
Record what remains unresolved. If service is restored but historical records still need correction, use separate statuses for those outcomes. Do not close the entire incident solely because the latest request returned successfully.
Use the HubSpot portal audit checklist to identify downstream processes that may need validation. Keep the acceptance criteria specific to the affected integration.
The following fictional incident note is a starting format. It contains no production records, credentials or actual service commitment. Replace the example values with sanitized evidence from your authorized environment.
Keep the note factual when the outcome is uncertain. A timeout is not enough evidence to conclude that nothing changed. Before replaying an uncertain operation, inspect the destination using the integration's approved identifiers and check the documented behavior of that operation. The runbook should identify who can make that decision.
List the routine read-only checks a responder may perform, such as reviewing a sanitized error and the current configuration reference. List consequential actions separately: changing scopes, rotating a credential, pausing a connection, editing a mapping or replaying a batch. Record the authorizing role and the evidence needed for each decision.
This distinction prevents a vague instruction to “fix sync” from becoming permission to alter the whole integration. If the documented correction no longer matches the observed failure, escalate with the evidence instead of improvising a broader change.
We recommend a tabletop exercise before relying on the document during an incident. Give an authorized colleague the fictional note and ask them to identify the affected process, owner, first check, prohibited actions and recovery test. A tabletop exercise does not prove the integration will recover, but it can reveal missing decisions without changing production.
No universal retry rule is appropriate. Review the actual endpoint, error and integration behavior. Check whether the earlier operation changed anything and whether repeating it can create an unwanted effect. Use a bounded, authorized correction and verify the result.
We recommend verifying the intended records and business outcome as well as current service operation. Keep any incomplete historical corrections visible even after new traffic succeeds.
Name an operating owner and a maintainer, with coverage for absences. Review the document when mappings, systems, permissions or responsibilities change. Do not leave ownership implied by whoever last edited it.
We recommend a clear front page with the purpose, owners, first checks, prohibited actions and escalation route. Link the detailed mapping, test evidence and change history from there. Review it whenever the integration or its ownership changes.
If your team needs help defining that operating responsibility, review HubSpot operations. Bring one real integration and ask whether another authorized person could diagnose, escalate and verify a failure using the documentation alone.
Product documentation checked August 29, 2026. Recheck endpoint behavior and limits before implementing retries, access changes or replay.